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The  MIT  License  (MIT)  Copyright  © Taylor  Otwell 

Permission  is  hereby  granted,  free  of  charge,  to  any  person  obtaining  a copy  of  this  software  and 
associated  documentation  files  (the  “Software”),  to  deal  in  the  Software  without  restriction,  including 
without  limitation  the  rights  to  use,  copy,  modify,  merge,  publish,  distribute,  sublicense,  and/or  sell 
copies  of  the  Software,  and  to  permit  persons  to  whom  the  Software  is  furnished  to  do  so,  subject  to 
the  following  conditions: 

The  above  copyright  notice  and  this  permission  notice  shall  be  included  in  all  copies  or  substantial 
portions  of  the  Software. 

THE  SOFTWARE  IS  PROVIDED  “AS  IS”,  WITHOUT  WARRANTY  OF  ANY  KIND,  EXPRESS  OR 
IMPLIED,  INCLUDING  BUT  NOT  LIMITED  TO  THE  WARRANTIES  OF  MERCHANTABILITY, 
FITNESS  FOR  A PARTICULAR  PURPOSE  AND  NONINFRINGEMENT  IN  NO  EVENT  SHALL 
THE  AUTHORS  OR  COPYRIGHT  HOLDERS  BE  LIABLE  FOR  ANY  CLAIM,  DAMAGES  OR 
OTHER  LIABILITY,  WHETHER  IN  AN  ACTION  OF  CONTRACT,  TORT  OR  OTHERWISE, 
ARISING  FROM,  OUT  OF  OR  IN  CONNECTION  WITH  THE  SOFTWARE  OR  THE  USE  OR  OTHER 
DEALINGS  IN  THE  SOFTWARE. 


Contribution  Guidelines 


If  you  are  submitting  documentation  for  the  current  stable  release,  submit  it  to  the  corresponding 
branch.  For  example,  documentation  for  Laravel  5.1  would  be  submitted  to  the  5.1  branch. 
Documentation  intended  for  the  next  release  of  Laravel  should  be  submitted  to  the  master  branch. 
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• Support  Policy 

• Laravel  5.2 

• Laravel  5.1.11 

• Laravel  5.1.4 

• Laravel  5.1 

• Laravel  5.0 

• Laravel  4.2 

• Laravel  4. 1 

Support  Policy 

For  LTS  releases,  such  as  Laravel  5.1,  bug  fixes  are  provided  for  2 years  and  security  fixes  are  provided 
for  3 years.  These  releases  provide  the  longest  window  of  support  and  maintenance. 

For  general  releases,  bug  fixes  are  provided  for  6 months  and  security  fixes  are  provided  for  1 year. 

Laravel  5.3  {#releases-laravel-5.3} 

Laravel  5.3  continues  the  improvements  made  in  Laravel  5.2. 

PHP  5.6.4+ 

Since  PHP  5.5  will  enter  “end  of  life”  in  June  and  will  no  longer  receive  security  updates  from  the 
PHP  development  team,  Laravel  5.3  requires  PHP  5.6.4  or  greater.  If  you  require  PHP  5.5  support, 
please  see  our  5.1  LTS  series. 

Laravel  5.2  {#releases-laravel-5.2} 

Laravel  5.2  continues  the  improvements  made  in  Laravel  5.1  by  adding  multiple  authentication  driver 
support,  implicit  model  binding,  simplified  Eloquent  global  scopes,  opt-in  authentication  scaffolding, 
middleware  groups,  rate  limiting  middleware,  array  validation  improvements,  and  more. 
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Authentication  Drivers  / "Multi-Auth" 

In  previous  versions  of  Laravel,  only  the  default,  session-based  authentication  driver  was  supported 
out  of  the  box,  and  you  could  not  have  more  than  one  authenticatable  model  instance  per  application. 

However,  in  Laravel  5.2,  you  may  define  additional  authentication  drivers  as  well  define  multiple 
authenticatable  models  or  user  tables,  and  control  their  authentication  process  separately  from  each 
other.  For  example,  if  your  application  has  one  database  table  for  “admin”  users  and  one  database 
table  for  “student”  users,  you  may  now  use  the  Auth  methods  to  authenticate  against  each  of  these 
tables  separately. 

Authentication  Scaffolding 

Laravel  already  makes  it  easy  to  handle  authentication  on  the  back-end;  however,  Laravel  5.2 
provides  a convenient,  lightning-fast  way  to  scaffold  the  authentication  views  for  your  front-end. 
Simply  execute  the  make : auth  command  on  your  terminal: 


1 php  artisan  make: auth 


This  command  will  generate  plain,  Bootstrap  compatible  views  for  user  login,  registration,  and 
password  reset.  The  command  will  also  update  your  routes  file  with  the  appropriate  routes. 


Note:  This  feature  is  only  meant  to  be  used  on  new  applications,  not  during  application 
upgrades. 


Implicit  Model  Binding 


Implicit  model  binding  makes  it  painless  to  inject  relevant  models  directly  into  your  routes  and 
controllers.  For  example,  assume  you  have  a route  defined  like  the  following: 


1 

use  App\User; 

2 

3 

Route : : get( ' /user/{user } ' 

function  (User  $user)  { 

4 

return  $user; 

5 

}); 

In  Laravel  5.1,  you  would  typically  need  to  use  the  Route:  : model  method  to  instruct  Laravel  to 
inject  the  App\User  instance  that  matches  the  {user}  parameter  in  your  route  definition.  However,  in 
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Laravel  5.2,  the  framework  will  automatically  inject  this  model  based  on  the  URI  segment,  allowing 
you  to  quickly  gain  access  to  the  model  instances  you  need. 

Laravel  will  automatically  inject  the  model  when  the  route  parameter  segment  ({user})  matches 
the  route  Closure  or  controller  method’s  corresponding  variable  name  ($user)  and  the  variable  is 
type-hinting  an  Eloquent  model  class. 

Middleware  Groups 

Middleware  groups  allow  you  to  group  several  route  middleware  under  a single,  convenient  key, 
allowing  you  to  assign  several  middleware  to  a route  at  once.  For  example,  this  can  be  useful  when 
building  a web  UI  and  an  API  within  the  same  application.  You  may  group  the  session  and  CSRF 
routes  into  a web  group,  and  perhaps  the  rate  limiter  in  the  api  group. 

In  fact,  the  default  Faravel  5.2  application  structure  takes  exactly  this  approach.  For  example,  in  the 
default  App\Http\Kernel . php  file  you  will  find  the  following: 


/** 

* The  application's  route  middleware  groups. 

* 

* §var  array 

V 

protected  $middlewareGroups  = [ 

'web'  =>  [ 

\App\Http\Middleware\EncryptCookies : : class, 

\I 1 luminate\Cookie\Middleware\AddQueuedCookiesToResponse : : class, 
\I 1 luminate\Session\Middleware\StartSession : : class, 

\I 1 luminate\View\Middleware\ShareErrorsFromSession : : class, 
\App\Http\Middleware\Veri fyCsr fToken : :class, 

1 , 

'api'  =>  [ 

' throttle : 60,1' , 

1, 


1 

2 

3 

4 

5 

6 

7 

8 
9 

10 

11 

12 

13 

14 

15 

16 

17 

18 


Then,  the  web  group  may  be  assigned  to  routes  like  so: 

1 Route :: group( [' middleware ' =>  [ ' web ' ] ] , function  ()  { 

2 // 
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3 }); 


Rate  Limiting 

A new  rate  limiter  middleware  is  now  included  with  the  framework,  allowing  you  to  easily  limit  the 
number  of  requests  that  a given  IP  address  can  make  to  a route  over  a specified  number  of  minutes. 
For  example,  to  limit  a route  to  60  requests  every  minute  from  a single  IP  address,  you  may  do  the 
following: 


1 

Route : : get( ' /api/users ' , 

['middleware'  =>  ' throttle : 60, 1 ' , function  ()  { 

2 

// 

3 

11); 

Array  Validation 

Validating  array  form  input  fields  is  much  easier  in  Laravel  5.2.  For  example,  to  validate  that  each 
e-mail  in  a given  array  input  field  is  unique,  you  may  do  the  following: 


1 Svalidator  = Val idator : : make($request->al 1 ( ) , [ 
' person . *. emai 1 ' =>  ' emai 1 I unique : users ' 

3 ]); 


Likewise,  you  may  use  the  * character  when  specifying  your  validation  messages  in  your  language 
files,  making  it  a breeze  to  use  a single  validation  message  for  array  based  fields: 

1 'custom'  =>  [ 

' person emai 1 ' =>  [ 

'unique'  =>  'Each  person  must  have  a unique  e-mail  address', 

4 1 

5 1, 
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Eloquent  Global  Scope  Improvements 

In  previous  versions  of  Laravel,  global  Eloquent  scopes  were  complicated  and  error-prone  to 
implement;  however,  in  Laravel  5.2,  global  query  scopes  only  require  you  to  implement  a single, 
simple  method:  apply. 

For  more  information  on  writing  global  scopes,  check  out  the  full  Eloquent  documentation. 

Laravel  5.1.11  {#releases-laravel-5.1.11} 

Laravel  5.1.11  introduces  authorization  support  out  of  the  box!  Conveniently  organize  your  appli- 
cation’s authorization  logic  using  simple  callbacks  or  policy  classes,  and  authorize  actions  using 
simple,  expressive  methods. 

For  more  information,  please  refer  to  the  authorization  documentation. 

Laravel  5.1.4  {#releases-laravel-5.1.4} 

Laravel  5.1.4  introduces  simple  login  throttling  to  the  framework.  Consult  the  authentication 
documentation  for  more  information. 

Laravel  5.1  {#releases-laravel-5.1} 

Laravel  5.1  continues  the  improvements  made  in  Laravel  5.0  by  adopting  PSR-2  and  adding  event 
broadcasting,  middleware  parameters,  Artisan  improvements,  and  more. 

PHP  5.5.9+ 


Since  PHP  5.4  will  enter  “end  of  life”  in  September  and  will  no  longer  receive  security  updates  from 
the  PHP  development  team,  Laravel  5.1  requires  PHP  5.5.9  or  greater.  PHP  5.5.9  allows  compatibility 
with  the  latest  versions  of  popular  PHP  libraries  such  as  Guzzle  and  the  AWS  SDK. 

LTS 

Laravel  5.1  is  the  first  release  of  Laravel  to  receive  long  term  support.  Laravel  5.1  will  receive  bug 
fixes  for  2 years  and  security  fixes  for  3 years.  This  support  window  is  the  largest  ever  provided  for 
Laravel  and  provides  stability  and  peace  of  mind  for  larger,  enterprise  clients  and  customers. 
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PSR-2 

The  PSR-2  coding  style  guide2  has  been  adopted  as  the  default  style  guide  for  the  Laravel  framework. 
Additionally,  all  generators  have  been  updated  to  generate  PSR-2  compatible  syntax. 

Documentation 

Every  page  of  the  Laravel  documentation  has  been  meticulously  reviewed  and  dramatically 
improved.  All  code  examples  have  also  been  reviewed  and  expanded  to  provide  more  relevance 
and  context. 

Event  Broadcasting 

In  many  modern  web  applications,  web  sockets  are  used  to  implement  real-time,  live-updating  user 
interfaces.  When  some  data  is  updated  on  the  server,  a message  is  typically  sent  over  a websocket 
connection  to  be  handled  by  the  client. 

To  assist  you  in  building  these  types  of  applications,  Laravel  makes  it  easy  to  “broadcast”  your  events 
over  a websocket  connection.  Broadcasting  your  Laravel  events  allows  you  to  share  the  same  event 
names  between  your  server-side  code  and  your  client-side  JavaScript  framework. 

To  learn  more  about  event  broadcasting,  check  out  the  event  documentation. 

Middleware  Parameters 

Middleware  can  now  receive  additional  custom  parameters.  Lor  example,  if  your  application  needs 
to  verify  that  the  authenticated  user  has  a given  “role”  before  performing  a given  action,  you  could 
create  a RoleMiddleware  that  receives  a role  name  as  an  additional  argument: 


1 < ?php 

2 

3 namespace  App\Http\Middleware; 

4 


5 

use  Closure; 

6 

7 

class  RoleMiddleware 

8 

{ 

9 

/** 

10 

* Run  the 

request  filter. 

11 

* 

12 

* §param 

\I 1 1 umi nate \Http \Request  Srequest 

13 

* §param 

\Closure  $next 

2https://gi  thub.com/php-fig/flg-standards/blob/master/accepted/PSR-2-coding-style-guide.md 
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14  * §param  string  $role 

15  * ©return  mixed 

16  */ 

public  function  handle($request,  Closure  $next,  $role) 

18  { 

19  if  (!  $request->user( )->hasRole($role))  { 

20  //  Redirect. . . 

21  } 

22 

23  return  $next($request) ; 

24  } 

25 

26  } 


Middleware  parameters  may  be  specified  when  defining  the  route  by  separating  the  middleware 
name  and  parameters  with  a : . Multiple  parameters  should  be  delimited  by  commas: 


1 Route :: put( ' post/{ id} ' , ['middleware'  =>  ' role : editor ' , function  ($id)  { 

2 // 

3 }]); 


For  more  information  on  middleware,  check  out  the  middleware  documentation. 

Testing  Overhaul 

The  built-in  testing  capabilities  of  Laravel  have  been  dramatically  improved.  A variety  of  new 
methods  provide  a fluent,  expressive  interface  for  interacting  with  your  application  and  examining 
its  responses.  For  example,  check  out  the  following  test: 

1 public  function  testNewUserRegistration( ) 

2 { 

$this- > visit( '/register' ) 

4 - >type( ' Taylor  1 , 'name') 

5 -> check (' terms ' ) 

6 ->press( 'Register ' ) 

- >seePageIs( ' /dashboard ' ) ; 

8 } 
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For  more  information  on  testing,  check  out  the  testing  documentation. 


Model  Factories 

Laravel  now  ships  with  an  easy  way  to  create  stub  Eloquent  models  using  model  factories.  Model 
factories  allow  you  to  easily  define  a set  of  “default”  attributes  for  your  Eloquent  model,  and  then 
generate  test  model  instances  for  your  tests  or  database  seeds.  Model  factories  also  take  advantage 
of  the  powerful  Faker3  PHP  library  for  generating  random  attribute  data: 


1 $factory->define(App\User : :class,  function  ($faker)  { 
return  [ 

'name'  =>  $faker->name, 

4 'email'  =>  $faker- >emai 1 , 

5 'password'  =>  str_random(10) , 

' remember_token ' =>  str_random(10) , 

7 ]; 

8 }); 


For  more  information  on  model  factories,  check  out  the  documentation. 

Artisan  Improvements 

Artisan  commands  may  now  be  defined  using  a simple,  route-like  “signature”,  which  provides  an 
extremely  simple  interface  for  defining  command  line  arguments  and  options.  For  example,  you 
may  define  a simple  command  and  its  options  like  so: 

1 /** 

2 * The  name  and  signature  of  the  console  command. 

3 * 

4 * §var  string 

5 V 

6 protected  Ssignature  = 'email: send  {user}  {--force}1; 


For  more  information  on  defining  Artisan  commands,  consult  the  Artisan  documentation. 


3https://github.com/fzaninotto/Faker 
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Folder  Structure 

To  better  express  intent,  the  app/Commands  directory  has  been  renamed  to  app/Jobs.  Additionally, 
the  app/Handlers  directory  has  been  consolidated  into  a single  app/Listeners  directory  which 
simply  contains  event  listeners.  However,  this  is  not  a breaking  change  and  you  are  not  required  to 
update  to  the  new  folder  structure  to  use  Laravel  5.1. 

Encryption 

In  previous  versions  of  Laravel,  encryption  was  handled  by  the  mcrypt  PHP  extension.  However, 
beginning  in  Laravel  5.1,  encryption  is  handled  by  the  openssl  extension,  which  is  more  actively 
maintained. 

Laravel  5.0  {#releases-laravel-5.0} 

Laravel  5.0  introduces  a fresh  application  structure  to  the  default  Laravel  project.  This  new  structure 
serves  as  a better  foundation  for  building  a robust  application  in  Laravel,  as  well  as  embraces  new 
auto-loading  standards  (PSR-4)  throughout  the  application.  First,  let’s  examine  some  of  the  major 
changes: 

New  Folder  Structure 

The  old  app/models  directory  has  been  entirely  removed.  Instead,  all  of  your  code  lives  directly 
within  the  app  folder,  and,  by  default,  is  organized  to  the  App  namespace.  This  default  namespace 
can  be  quickly  changed  using  the  new  app : name  Artisan  command. 

Controllers,  middleware,  and  requests  (a  new  type  of  class  in  Laravel  5.0)  are  now  grouped  under  the 
app/Http  directory,  as  they  are  all  classes  related  to  the  HTTP  transport  layer  of  your  application. 
Instead  of  a single,  flat  file  of  route  filters,  all  middleware  are  now  broken  into  their  own  class  files. 

A new  app/Providers  directory  replaces  the  app/start  fdes  from  previous  versions  of  Laravel 
4.x.  These  service  providers  provide  various  bootstrapping  functions  to  your  application,  such  as 
error  handling,  logging,  route  loading,  and  more.  Of  course,  you  are  free  to  create  additional  service 
providers  for  your  application. 

Application  language  files  and  views  have  been  moved  to  the  resources  directory. 

Contracts 

All  major  Laravel  components  implement  interfaces  which  are  located  in  the  i 1 lumi  nate/contracts 
repository.  This  repository  has  no  external  dependencies.  Having  a convenient,  centrally  located  set 
of  interfaces  you  may  use  for  decoupling  and  dependency  injection  will  serve  as  an  easy  alternative 
option  to  Laravel  Facades. 

For  more  information  on  contracts,  consult  the  full  documentation. 
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Route  Cache 

If  your  application  is  made  up  entirely  of  controller  routes,  you  may  utilize  the  new  route:  cache 
Artisan  command  to  drastically  speed  up  the  registration  of  your  routes.  This  is  primarily  useful  on 
applications  with  100+  routes  and  will  drastically  speed  up  this  portion  of  your  application. 

Route  Middleware 

In  addition  to  Laravel  4 style  route  “filters”,  Laravel  5 now  supports  HTTP  middleware,  and 
the  included  authentication  and  CSRF  “filters”  have  been  converted  to  middleware.  Middleware 
provides  a single,  consistent  interface  to  replace  all  types  of  filters,  allowing  you  to  easily  inspect, 
and  even  reject,  requests  before  they  enter  your  application. 

For  more  information  on  middleware,  check  out  the  documentation. 

Controller  Method  Injection 

In  addition  to  the  existing  constructor  injection,  you  may  now  type-hint  dependencies  on  controller 
methods.  The  service  container  will  automatically  inject  the  dependencies,  even  if  the  route  contains 
other  parameters: 


1 public  function  createPost( Request  $request,  PostRepository  $posts) 

2 { 

3 // 

4 } 


Authentication  Scaffolding 

User  registration,  authentication,  and  password  reset  controllers  are  now  included  out  of  the  box, 
as  well  as  simple  corresponding  views,  which  are  located  at  resources/views/auth.  In  addition, 
a “users”  table  migration  has  been  included  with  the  framework.  Including  these  simple  resources 
allows  rapid  development  of  application  ideas  without  bogging  down  on  authentication  boilerplate. 
The  authentication  views  may  be  accessed  on  the  auth/login  and  auth/register  routes.  The 
App\Services\Auth\Registrar  service  is  responsible  for  user  validation  and  creation. 

Event  Objects 

You  may  now  define  events  as  objects  instead  of  simply  using  strings.  For  example,  check  out  the 
following  event: 
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1 < ?php 

2 

3 class  PodcastWasPurchased 

4 { 

5 public  $podcast; 

6 

public  function  construct( Podcast  $podcast) 

8 { 

9 $this- >podcast  = $podcast; 

10  } 

11  } 


The  event  may  be  dispatched  like  normal: 


1 Event :: fire(new  PodcastWasPurchased(Spodcast) ) ; 


Of  course,  your  event  handler  will  receive  the  event  object  instead  of  a list  of  data: 


1 < ?php 

2 

3 class  ReportPodcastPurchase 

4 { 

5 public  function  hand le( PodcastWasPurchased  $event) 

6 { 

7 // 

8 } 

9 1 


For  more  information  on  working  with  events,  check  out  the  full  documentation. 

Commands  / Queueing 

In  addition  to  the  queue  job  format  supported  in  Laravel  4,  Laravel  5 allows  you  to  represent  your 
queued  jobs  as  simple  command  objects.  These  commands  live  in  theapp/Commands  directory.  Here’s 
a sample  command: 
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1 < ?php 

2 

3 class  PurchasePodcast  extends  Command  implements  Sel fHandl ing,  ShouldBeQueued 

4 { 

5 use  Serial izesModels; 

6 

7 protected  $user,  $podcast; 

8 

g /** 

10  * Create  a new  command  instance. 

11  * 

12  * §return  void 

13  */ 

public  function  construct(User  $user,  Podcast  $podcast) 

15  { 

16  $this->user  = $user; 

17  $this- >podcast  = $podcast; 

18  } 

19 

20  /** 

21  * Execute  the  command. 

22  * 

23  * @return  void 

24  */ 

25  public  function  handle() 

26  { 

27  //  Handle  the  logic  to  purchase  the  podcast. . . 

28 

event(new  PodcastWasPurchased($this->user,  $this- >podcast) ) ; 

30  } 

31  } 


The  base  Laravel  controller  utilizes  the  new  DispatchesCommands  trait,  allowing  you  to  easily 
dispatch  your  commands  for  execution: 


1 $this->dispatch(new  PurchasePodcastCommand($user , $podcast)); 


Of  course,  you  may  also  use  commands  for  tasks  that  are  executed  synchronously  (are  not  queued). 
In  fact,  using  commands  is  a great  way  to  encapsulate  complex  tasks  your  application  needs  to 
perform.  For  more  information,  check  out  the  command  bus  documentation. 
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Database  Queue 

A database  queue  driver  is  now  included  in  Laravel,  providing  a simple,  local  queue  driver  that 
requires  no  extra  package  installation  beyond  your  database  software. 


Laravel  Scheduler 

In  the  past,  developers  have  generated  a Cron  entry  for  each  console  command  they  wished  to 
schedule.  However,  this  is  a headache.  Your  console  schedule  is  no  longer  in  source  control,  and 
you  must  SSH  into  your  server  to  add  the  Cron  entries.  Let’s  make  our  lives  easier.  The  Laravel 
command  scheduler  allows  you  to  fluently  and  expressively  define  your  command  schedule  within 
Laravel  itself,  and  only  a single  Cron  entry  is  needed  on  your  server. 

It  looks  like  this: 

1 $schedule- >command( ' artisan : command ' )->dailyAt( '15:00' ) ; 


Of  course,  check  out  the  full  documentation  to  learn  all  about  the  scheduler! 

Tinker  / Psysh 

The  php  artisan  tinker  command  now  utilizes  Psysh4  by  Justin  Hileman,  a more  robust  REPL  for 
PHP.  If  you  liked  Boris  in  Laravel  4,  you’re  going  to  love  Psysh.  Even  better,  it  works  on  Windows! 
To  get  started,  just  try: 

1 php  artisan  tinker 


DotEnv 

Instead  of  a variety  of  confusing,  nested  environment  configuration  directories,  Laravel  5 now 
utilizes  DotEnv5  by  Vance  Lucas.  This  library  provides  a super  simple  way  to  manage  your 
environment  configuration,  and  makes  environment  detection  in  Laravel  5 a breeze.  For  more  details, 
check  out  the  full  configuration  documentation. 


4https :/ /github . com/bobtheco  w/psy  sh 

5https://github.com/vlucas/phpdotenv 
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Laravel  Elixir 

Laravel  Elixir,  by  Jeffrey  Way,  provides  a fluent,  expressive  interface  to  compiling  and  concatenating 
your  assets.  If  you’ve  ever  been  intimidated  by  learning  Grunt  or  Gulp,  fear  no  more.  Elixir  makes  it 
a cinch  to  get  started  using  Gulp  to  compile  your  Less,  Sass,  and  CoffeeScript.  It  can  even  run  your 
tests  for  you! 

For  more  information  on  Elixir,  check  out  the  full  documentation. 


Laravel  Socialite 

Laravel  Socialite  is  an  optional,  Laravel  5.0+  compatible  package  that  provides  totally  painless 
authentication  with  OAuth  providers.  Currently,  Socialite  supports  Facebook,  Twitter,  Google,  and 
GitHub.  Here’s  what  it  looks  like: 


1 public  function  redirectForAuth( ) 

2 { 

return  Social ize : : with( ' twitter ' ) ->redirect( ) ; 

4 } 

5 

6 public  function  getllserFromProvider( ) 

7 { 

$user  = Social ize :: with( ' twitter ')- >user( ) ; 

9 } 


No  more  spending  hours  writing  OAuth  authentication  flows.  Get  started  in  minutes!  The  full 
documentation  has  all  the  details. 

Flysystem  Integration 

Laravel  now  includes  the  powerful  Flysystem6  filesystem  abstraction  library,  providing  pain  free 
integration  with  local,  Amazon  S3,  and  Rackspace  cloud  storage  - all  with  one,  unified  and  elegant 
API!  Storing  a file  in  Amazon  S3  is  now  as  simple  as: 


1 Storage :: put( ' fi le . txt ' , 'contents'); 


For  more  information  on  the  Laravel  Flysystem  integration,  consult  the  full  documentation. 


6https://github.com/thephpleague/flysystem 
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Form  Requests 

Laravel  5.0  introduces  form  requests,  which  extend  the  1 1 luminate\Foundation\Http\FormRequest 
class.  These  request  objects  can  be  combined  with  controller  method  injection  to  provide  a boiler- 
plate free  method  of  validating  user  input.  Let’s  dig  in  and  look  at  a sample  FormRequest: 


1 < ?php 

2 

3 namespace  App\Http\Requests; 

4 

5 class  RegisterRequest  extends  FormRequest 

6 { 

7 public  function  rules() 

8 { 

9 return  [ 

10  'email'  =>  ' required  I emai 1 [ unique : users ' , 

11  'password'  =>  ' required  I confirmed  I min : 8 ' , 

12  ]; 

13  } 

14 

15  public  function  authorizeQ 

16  { 

17  return  true; 

18  } 

19  } 


Once  the  class  has  been  defined,  we  can  type-hint  it  on  our  controller  action: 


1 public  function  register(RegisterRequest  Srequest) 

2 { 

var_dump($request- > input( ) ) ; 

4 } 


When  the  Laravel  service  container  identifies  that  the  class  it  is  injecting  is  a FormRequest  instance, 
the  request  will  automatically  be  validated.  This  means  that  if  your  controller  action  is  called,  you 
can  safely  assume  the  HTTP  request  input  has  been  validated  according  to  the  rules  you  specified 
in  your  form  request  class.  Even  more,  if  the  request  is  invalid,  an  HTTP  redirect,  which  you  may 
customize,  will  automatically  be  issued,  and  the  error  messages  will  be  either  flashed  to  the  session 
or  converted  to  JSON.  Form  validation  has  never  been  more  simple.  For  more  information  on 
FormRequest  validation,  check  out  the  documentation. 
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Simple  Controller  Request  Validation 

The  Laravel  5 base  controller  now  includes  a ValidatesRequests  trait.  This  trait  provides  a simple 
validate  method  to  validate  incoming  requests.  If  FormRequests  are  a little  too  much  for  your 
application,  check  this  out: 

1 public  function  createPost(Request  Irequest) 

2 { 

$this->validate($request,  [ 

4 'title'  =>  ' required  I max : 255 ' , 

5 'body'  =>  'required', 

6 ]); 

7 } 


If  the  validation  fails,  an  exception  will  be  thrown  and  the  proper  HTTP  response  will  automatically 
be  sent  back  to  the  browser.  The  validation  errors  will  even  be  flashed  to  the  session!  If  the  request 
was  an  AJAX  request,  Laravel  even  takes  care  of  sending  a JSON  representation  of  the  validation 
errors  back  to  you. 

For  more  information  on  this  new  method,  check  out  the  documentation. 


New  Generators 

To  complement  the  new  default  application  structure,  new  Artisan  generator  commands  have  been 
added  to  the  framework.  See  php  artisan  list  for  more  details. 

Configuration  Cache 

You  may  now  cache  all  of  your  configuration  in  a single  file  using  the  conf  ig : cache  command. 

Symfony  VarDumper 

The  popular  dd  helper  function,  which  dumps  variable  debug  information,  has  been  upgraded  to  use 
the  amazing  Symfony  VarDumper.  This  provides  color-coded  output  and  even  collapsing  of  arrays. 
Just  try  the  following  in  your  project: 

1 dd(  [1 , 2,  3]); 
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Laravel  4.2 


The  full  change  list  for  this  release  by  running  the  php  artisan  changes  command  from  a 
4.2  installation,  or  by  viewing  the  change  file  on  Github7.  These  notes  only  cover  the  major 
enhancements  and  changes  for  the  release. 


Note:  During  the  4.2  release  cycle,  many  small  bug  fixes  and  enhancements  were  incor- 
porated into  the  various  Laravel  4.1  point  releases.  So,  be  sure  to  check  the  change  list  for 
Laravel  4.1  as  well! 


PHP  5.4  Requirement 

Laravel  4.2  requires  PHP  5.4  or  greater.  This  upgraded  PHP  requirement  allows  us  to  use  new  PHP 
features  such  as  traits  to  provide  more  expressive  interfaces  for  tools  like  Laravel  Cashier.  PHP  5.4 
also  brings  significant  speed  and  performance  improvements  over  PHP  5.3. 

Laravel  Forge 

Laravel  Forge,  a new  web  based  application,  provides  a simple  way  to  create  and  manage  PHP 
servers  on  the  cloud  of  your  choice,  including  Linode,  DigitalOcean,  Rackspace,  and  Amazon  EC2. 
Supporting  automated  Nginx  configuration,  SSH  key  access,  Cron  job  automation,  server  monitoring 
via  NewRelic  & Papertrail,  “Push  To  Deploy”,  Laravel  queue  worker  configuration,  and  more,  Forge 
provides  the  simplest  and  most  affordable  way  to  launch  all  of  your  Laravel  applications. 

The  default  Laravel  4.2  installation’s  app/config/database.  php  configuration  file  is  now  configured 
for  Forge  usage  by  default,  allowing  for  more  convenient  deployment  of  fresh  applications  onto  the 
platform. 

More  information  about  Laravel  Forge  can  be  found  on  the  official  Forge  website8. 


Laravel  Homestead 

Laravel  Homestead  is  an  official  Vagrant  environment  for  developing  robust  Laravel  and  PHP 
applications.  The  vast  majority  of  the  boxes’  provisioning  needs  are  handled  before  the  box 
is  packaged  for  distribution,  allowing  the  box  to  boot  extremely  quickly.  Homestead  includes 
Nginx  1.6,  PHP  5.6,  MySQL,  Postgres,  Redis,  Memcached,  Beanstalk,  Node,  Gulp,  Grunt,  & Bower. 
Homestead  includes  a simple  Homestead . yaml  configuration  file  for  managing  multiple  Laravel 
applications  on  a single  box. 


7 https  ://github . com/laravel/framework/blob/4. 2/src/Illuminate/Foundation/ changes. j son 

8https://forge.laravel.com 
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The  default  Laravel  4.2  installation  now  includes  an  app/con  fig/ local /database . php  configuration 
file  that  is  configured  to  use  the  Homestead  database  out  of  the  box,  making  Laravel  initial 
installation  and  configuration  more  convenient. 

The  official  documentation  has  also  been  updated  to  include  Homestead  documentation. 


Laravel  Cashier 

Laravel  Cashier  is  a simple,  expressive  library  for  managing  subscription  billing  with  Stripe.  With 
the  introduction  of  Laravel  4.2,  we  are  including  Cashier  documentation  along  with  the  main  Laravel 
documentation,  though  installation  of  the  component  itself  is  still  optional.  This  release  of  Cashier 
brings  numerous  bug  fixes,  multi-currency  support,  and  compatibility  with  the  latest  Stripe  API. 


Daemon  Queue  Workers 

The  Artisan  queue: work  command  now  supports  a - -daemon  option  to  start  a worker  in  “daemon 
mode”,  meaning  the  worker  will  continue  to  process  jobs  without  ever  re-booting  the  framework. 
This  results  in  a significant  reduction  in  CPU  usage  at  the  cost  of  a slightly  more  complex  application 
deployment  process. 

More  information  about  daemon  queue  workers  can  be  found  in  the  queue  documentation. 


Mail  API  Drivers 

Laravel  4.2  introduces  new  Mailgun  and  Mandrill  API  drivers  for  the  Mail  functions.  For  many 
applications,  this  provides  a faster  and  more  reliable  method  of  sending  e-mails  than  the  SMTP 
options.  The  new  drivers  utilize  the  Guzzle  4 HTTP  library. 

Soft  Deleting  Traits 


A much  cleaner  architecture  for  “soft  deletes”  and  other  “global  scopes”  has  been  introduced  via 
PHP  5.4  traits.  This  new  architecture  allows  for  the  easier  construction  of  similar  global  traits,  and 
a cleaner  separation  of  concerns  within  the  framework  itself. 

More  information  on  the  new  SoftDeletingTrait  may  be  found  in  the  Eloquent  documentation. 


Convenient  Auth  & Remindable  Traits 

The  default  Laravel  4.2  installation  now  uses  simple  traits  for  including  the  needed  properties  for  the 
authentication  and  password  reminder  user  interfaces.  This  provides  a much  cleaner  default  User 
model  file  out  of  the  box. 
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"Simple  Paginate" 

A new  simp lePaginate  method  was  added  to  the  query  and  Eloquent  builder  which  allows  for  more 
efficient  queries  when  using  simple  “Next”  and  “Previous”  links  in  your  pagination  view. 

Migration  Confirmation 

In  production,  destructive  migration  operations  will  now  ask  for  confirmation.  Commands  may  be 
forced  to  run  without  any  prompts  using  the  - - force  command. 

Laravel  4.1 

Full  Change  List 

The  full  change  list  for  this  release  by  running  the  php  artisan  changes  command  from  a 
4.1  installation,  or  by  viewing  the  change  file  on  Github9.  These  notes  only  cover  the  major 
enhancements  and  changes  for  the  release. 

New  SSH  Component 

An  entirely  new  SSH  component  has  been  introduced  with  this  release.  This  feature  allows  you 
to  easily  SSH  into  remote  servers  and  run  commands.  To  learn  more,  consult  the  SSH  component 
documentation. 

The  new  php  artisan  tail  command  utilizes  the  new  SSH  component.  For  more  information, 
consult  the  tail  command  documentation10. 

Boris  In  Tinker 

The  php  artisan  tinker  command  now  utilizes  the  Boris  REPL* 11  if  your  system  supports  it.  The 
readline  and  pcntl  PHP  extensions  must  be  installed  to  use  this  feature.  If  you  do  not  have  these 
extensions,  the  shell  from  4.0  will  be  used. 

Eloquent  Improvements 

A new  hasManyThrough  relationship  has  been  added  to  Eloquent.  To  learn  how  to  use  it,  consult  the 
Eloquent  documentation. 

A new  whereHas  method  has  also  been  introduced  to  allow  retrieving  models  based  on  relationship 
constraints. 

9https://github.com/laravel/framework/blob/4.1/src/Illummate/Foundation/changes.json 
10http://laravel.com/docs/ssh#tailing-  remote- logs 

1 1https://gi  thub.com/  dl  lwtq/boris 
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Database  Read  / Write  Connections 

Automatic  handling  of  separate  read  / write  connections  is  now  available  throughout  the  database 
layer,  including  the  query  builder  and  Eloquent.  For  more  information,  consult  the  documentation. 

Queue  Priority 

Queue  priorities  are  now  supported  by  passing  a comma-delimited  list  to  the  queue:  listen 
command. 

Failed  Queue  Job  Handling 

The  queue  facilities  now  include  automatic  handling  of  failed  jobs  when  using  the  new  --tries 
switch  on  queue:  listen.  More  information  on  handling  failed  jobs  can  be  found  in  the  queue 
documentation. 

Cache  Tags 

Cache  “sections”  have  been  superseded  by  “tags”.  Cache  tags  allow  you  to  assign  multiple  “tags”  to 
a cache  item,  and  flush  all  items  assigned  to  a single  tag.  More  information  on  using  cache  tags  may 
be  found  in  the  cache  documentation. 

Flexible  Password  Reminders 

The  password  reminder  engine  has  been  changed  to  provide  greater  developer  flexibility  when 
validating  passwords,  flashing  status  messages  to  the  session,  etc.  For  more  information  on  using 
the  enhanced  password  reminder  engine,  consult  the  documentation. 

Improved  Routing  Engine 

Faravel  4.1  features  a totally  re-written  routing  layer.  The  API  is  the  same;  however,  registering 
routes  is  a full  100%  faster  compared  to  4.0.  The  entire  engine  has  been  greatly  simplified,  and  the 
dependency  on  Symfony  Routing  has  been  minimized  to  the  compiling  of  route  expressions. 

Improved  Session  Engine 

With  this  release,  we’re  also  introducing  an  entirely  new  session  engine.  Similar  to  the  routing 
improvements,  the  new  session  layer  is  leaner  and  faster.  We  are  no  longer  using  Symfony’ s (and 
therefore  PHP’s)  session  handling  facilities,  and  are  using  a custom  solution  that  is  simpler  and 
easier  to  maintain. 
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Doctrine  DBAL 

If  you  are  using  the  renameCo  1 umn  function  in  your  migrations,  you  will  need  to  add  the  doctr  i ne/d - 
ba  1 dependency  to  your  composer . j son  file.  This  package  is  no  longer  included  in  Laravel  by  default. 
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Upgrading  To  5.2.0  From  5.1  {#upgrade-upgrade-5.2.0} 

Estimated  Upgrade  Time:  Less  Than  1 Hour 


Note:  We  attempt  to  provide  a very  comprehensive  listing  of  every  possible  breaking 
change  made  to  the  framework.  However,  many  of  these  changes  may  not  apply  to  your 
own  application. 


Updating  Dependencies 

Update  your  composer . j son  file  to  point  to  1 ara ve  1 / framework  5.2.*. 

Add  "symfony/dom-crawler" : "~3.0"  and  "symfony/css-selector" : "~3.0"  to  the  require- 
dev  section  of  your  composer . json  file. 


Authentication 

Configuration  File 

You  should  update  your  con  f i g/auth . php  configuration  file  with  the  following:  https://github.eom/laravel/laravel/b 

1 2https :/ /github . com/laravel/laravel/blob/master/config/auth  .php 
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Once  you  have  updated  the  file  with  a fresh  copy,  set  your  authentication  configuration  options 
to  their  desired  value  based  on  your  old  configuration  file.  If  you  were  using  the  typical,  Eloquent 
based  authentication  services  available  in  Laravel  5.1,  most  values  should  remain  the  same. 

Take  special  note  of  the  passwords . users . email  configuration  option  in  the  new  auth . php  config- 
uration file  and  verify  that  the  view  path  matches  the  actual  view  path  for  your  application,  as  the 
default  path  to  this  view  was  changed  in  Laravel  5.2.  If  the  default  value  in  the  new  configuration 
file  does  not  match  your  existing  view,  update  the  configuration  option. 

Contracts 

If  you  are  implementing  the  Illuminate\Contracts\Auth\Authenticatable  contract  but  are  not 
using  the  Authenti eatable  trait,  you  should  add  a new  getAuthldenti f ierName  method  to  your 
contract  implementation.  Typically,  this  method  will  return  the  column  name  of  the  “primary  key” 
of  your  authenticatable  entity.  For  example:  id. 

This  is  unlikely  to  affect  your  application  unless  you  were  manually  implementing  this  interface. 

Custom  Drivers 

If  you  are  using  the  Auth : : extend  method  to  define  a custom  method  of  retrieving  users,  you  should 
now  use  Auth : : provider  to  define  your  custom  user  provider.  Once  you  have  defined  the  custom 
provider,  you  may  configure  it  in  the  providers  array  of  your  new  auth . php  configuration  file. 

For  more  information  on  custom  authentication  providers,  consult  the  full  authentication  documen- 
tation. 

Redirection 

The  loginPath( ) method  has  been  removed  from  1 1 1 um  i nate \Foundat  i on  \Auth\Authenti  cates  Users, 
so  placing  a $loginPath  variable  in  your  AuthControl  ler  is  no  longer  required.  By  default,  the  trait 
will  always  redirect  users  back  to  their  previous  location  on  authentication  errors. 

Authorization 

The  1 1 luminate\Auth\Access\UnauthorizedException  has  been  renamed  to  1 1 luminate\Auth\Access\Authoriza 
This  is  unlikely  to  affect  your  application  if  you  are  not  manually  catching  this  exception. 

Collections 

Eloquent  Base  Collections 

The  Eloquent  collection  instance  now  returns  a base  Collection  (1 1 luminate\Support\Col  lection) 
for  the  following  methods:  pluck,  keys,  zip,  collapse,  flatten,  flip. 
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Key  Preservation 

The  slice,  chunk,  and  reverse  methods  now  preserve  keys  on  the  collection.  If  you  do  not  want 
these  methods  to  preserve  keys,  use  the  values  method  on  the  Collection  instance. 

Composer  Class 

The  1 1 luminate\Foundation\Composer  class  has  been  moved  to  1 1 luminate\Support\Composer. 

This  is  unlikely  to  affect  your  application  if  you  were  not  manually  using  this  class. 

Commands  And  Handlers 

Self-Handling  Commands 

You  no  longer  need  to  implement  the  Sel  fHandl  ing  contract  on  your  jobs  / commands.  All  jobs  are 
now  self-handling  by  default,  so  you  can  remove  this  interface  from  your  classes. 

Separate  Commands  & Handlers 

The  Laravel  5.2  command  bus  now  only  supports  self-handling  commands  and  no  longer  supports 
separate  commands  and  handlers. 

If  you  would  like  to  continue  using  separate  commands  and  handlers,  you  may  install  a Laravel  Col- 
lective package  which  provides  backwards-compatible  support  for  this:  https://github.com/LaravelCollective/bus13 

Configuration 

Environment  Value 

Add  an  env  configuration  option  to  your  app . php  configuration  file  that  looks  like  the  following: 

1 'env'  =>  env( 'APP_ENV' , 'production'), 


Caching  And  Env 

If  you  are  using  the  conf  ig : cache  command  during  deployment,  you  must  make  sure  that  you  are 
only  calling  the  env  function  from  within  your  configuration  files,  and  not  from  anywhere  else  in 
your  application. 

If  you  are  calling  env  from  within  your  application,  it  is  strongly  recommended  you  add  proper 
configuration  values  to  your  configuration  files  and  call  env  from  that  location  instead,  allowing 
you  to  convert  your  env  calls  to  con  fig  calls. 

1 3https  ://github . com/laravelcollective/bus 
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Compiled  Classes 

If  present,  remove  the  following  lines  from  conf  ig/compi  le . php  in  the  files  array: 

1 realpath( DIR . ' / . . /app/Providers/BusServiceProvider . php ' ) , 

2 realpath( DIR . ' / ■ ■ /app/Providers/Conf igServiceProvider . php 1 ) , 


Not  doing  so  can  trigger  an  error  when  running  php  artisan  optimize  if  the  service  providers 
listed  here  do  not  exist. 

CSRF  Verification 

CSRF  verification  is  no  longer  automatically  performed  when  running  unit  tests.  This  is  unlikely  to 
affect  your  application. 


Database 

MySQL  Dates 

Starting  with  MySQL  5.7,  0000-00-00  00:00:00  is  no  longer  considered  a valid  date,  since  strict 
mode  is  enabled  by  default.  All  timestamp  columns  should  receive  a valid  default  value  when  you 
insert  records  into  your  database.  You  may  use  the  useCurrent  method  in  your  migrations  to  default 
the  timestamp  columns  to  the  current  timestamps,  or  you  may  make  the  timestamps  nullable  to 
allow  null  values: 

1 $table- >timestamp( 1 foo ' )->nullable(); 

2 

3 Stable- >timestamp( 1 foo ' ) - >useCurrent( ) ; 

4 

5 Stable- >nul lableTimestamps( ) ; 


MySQLJSON  Column  Type 

The  json  column  type  now  creates  actual  JSON  columns  when  used  by  the  MySQL  driver.  If  you 
are  not  running  MySQL  5.7  or  above,  this  column  type  will  not  be  available  to  you.  Instead,  use  the 
text  column  type  in  your  migration. 
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Seeding 

When  running  database  seeds,  all  Eloquent  models  are  now  unguarded  by  default.  Previously 
a call  to  Model:  :unguard()  was  required.  You  can  call  Model:  :reguard()  at  the  top  of  your 
DatabaseSeeder  class  if  you  would  like  models  to  be  guarded  during  seeding. 

Eloquent 

Date  Casts 

Any  attributes  that  have  been  added  to  your  $casts  property  as  date  or  datetime  will  now  be 
converted  to  a string  when  toArray  is  called  on  the  model  or  collection  of  models.  This  makes  the 
date  casting  conversion  consistent  with  dates  specified  in  your  $dates  array. 

Global  Scopes 

The  global  scopes  implementation  has  been  re-written  to  be  much  easier  to  use.  Your  global  scopes 
no  longer  need  a remove  method,  so  it  may  be  removed  from  any  global  scopes  you  have  written. 

If  you  were  calling  getQuery  on  an  Eloquent  query  builder  to  access  the  underlying  query  builder 
instance,  you  should  now  call  toBase. 

If  you  were  calling  the  remove  method  directly  for  any  reason,  you  should  change  this  call  to 
$eloquentBui lder- > withoutGlobal Scope ($scope). 

New  methods  withoutGlobal  Scope  and  withoutGlobal  Scopes  have  been  added  to  the  Eloquent 
query  builder.  Any  calls  to  $model->removeGlobalScopes($builder)  may  be  changed  to  simply 
$bui lder- > withoutGlobal Scopes ( ). 


Primary  keys 

By  default,  Eloquent  assumes  your  primary  keys  are  integers  and  will  automatically  cast  them  to 
integers.  For  any  primary  key  that  is  not  an  integer  you  should  override  the  $ incrementing  property 
on  your  Eloquent  model  to  false: 


1 /** 

2 * Indicates  if  the  IDs  are  auto- incrementing . 

3 * 

4 * §var  bool 

5 */ 

6 public  $incrementing  = true; 
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Events 

Core  Event  Objects 

Some  of  the  core  events  fired  by  Laravel  now  use  event  objects  instead  of  string  event  names  and 
dynamic  parameters.  Below  is  a list  of  the  old  event  names  and  their  new  object  based  counterparts: 

Old  | New | artisan . start  | 1 1 luminate\Console\Events\ArtisanStarting 

auth . attempting  1 1 1 luminate\Auth\Events\Attempting  auth . login  1 1 1 luminate\Auth\Events\Login 
auth . logout | 1 1 luminate\Auth\Events\Logout  cache . missed  1 1 1 luminate\Cache\Events\CacheMissed 
cache .hit  | 1 1 luminate\Cache\Events\CacheHit  cache . write 1 1 1 luminate\Cache\Events\KeyWritten 
cache. delete  | 1 1 luminate\Cache\Events\KeyForgotten  connection . {name} . beginTransaction 
| 1 1 luminate\Database\Events\TransactionBeginning  connection . {name} . committed  | Illumi- 
nate\Database\Events\TransactionCommitted  connection . {name} . rol 1 ingBack | 1 1 luminate\Database\Events 
i 1 luminate . query  | 1 1 luminate\Database\Events\QueryExecuted  i 1 luminate . queue . after  | II- 
luminate\Queue\Events\JobProcessed  i 1 luminate . queue . failed  1 1 1 luminate \Queue\Events\JobFai led 
i 1 luminate . queue . stopping  | 1 1 luminate\Queue\Events\WorkerStopping  mai ler . sending  | II- 
luminate\Mai 1 \Events\MessageSending  router . matched  1 1 1 luminate\Routing\Events\RouteMatched 

Each  of  these  event  objects  contains  exactly  the  same  parameters  that  were  passed  to  the  event 
handler  in  Laravel  5.1.  For  example,  if  you  were  using  DB : : 1 isten  in  5.1.,  you  may  update  your  code 
like  so  for  5.2.: 

1 DB :: 1 isten( function  ($event)  { 
dump($event->sql ) ; 
dump($event->bindings) ; 

4 }); 


You  may  check  out  each  of  the  new  event  object  classes  to  see  their  public  properties. 

Exception  Handling 

Your  App\Exceptions\Handler  class’  $dontReport  property  should  be  updated  to  include  at  least 
the  following  exception  types: 
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1 use  1 1 luminate\Val idation\Val idationException; 

2 use  1 1 luminate\Auth\Access\AuthorizationException; 

3 use  1 1 luminate\Database\Eloquent\ModelNotFoundException; 

4 use  Symfony\Component\HttpKernel\Exception\HttpException; 

5 

6 /** 

7 * A list  of  the  exception  types  that  should  not  be  reported. 

8 * 

9 * @var  array 

10  */ 

11  protected  $dontReport  = [ 

12  AuthorizationException : :class, 

13  HttpException: :class, 

14  ModelNotFoundException : :class, 

15  Val idationException :: class, 

16  ]; 


Helper  Functions 

The  url()  helper  function  now  returns  a 1 1 luminate\Routing\UrlGenerator  instance  when  no 
path  is  provided. 

Implicit  Model  Binding 

Laravel  5.2  includes  "implicit  model  binding”,  a convenient  new  feature  to  automatically  inject 
model  instances  into  routes  and  controllers  based  on  the  identifier  present  in  the  URI.  However, 
this  does  change  the  behavior  of  routes  and  controllers  that  type-hint  model  instances. 

If  you  were  type-hinting  a model  instance  in  your  route  or  controller  and  were  expecting  an  empty 
model  instance  to  be  injected,  you  should  remove  this  type-hint  and  create  an  empty  model  instance 
directly  within  your  route  or  controller;  otherwise,  Laravel  will  attempt  to  retrieve  an  existing  model 
instance  from  the  database  based  on  the  identifier  present  in  the  route’s  URI. 


IronMQ 

The  IronMQ  queue  driver  has  been  moved  into  its  own  package  and  is  no  longer  shipped  with  the 
core  framework. 

http://github.com/LaravelCollective/iron-queue14 

1 4http  ://github . com/laravelcollective/iron-  queue 
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Jobs  / Queue 


The  php  artisan  make : job  command  now  creates  a “queued”  job  class  definition  by  default.  If  you 
would  like  to  create  a “sync”  job,  use  the  - - sync  option  when  issuing  the  command. 

Mail 

The  pretend  mail  configuration  option  has  been  removed.  Instead,  use  the  log  mail  driver,  which 
performs  the  same  function  as  pretend  and  logs  even  more  information  about  the  mail  message. 

Pagination 

To  be  consistent  with  other  URLs  generated  by  the  framework,  the  paginator  URLs  no  longer  contain 
a trailing  slash.  This  is  unlikely  to  affect  your  application. 


Service  Providers 

The  II luminate\Foundation\Providers\ArtisanServiceProvider  should  be  removed  from  your 
service  provider  list  in  your  app . php  configuration  file. 

The  Illuminate \Rout  i ng  \Contro  1 1 erServ i ceProv i der  should  be  removed  from  your  service  provider 
list  in  your  app . php  configuration  file. 


Sessions 

Because  of  changes  to  the  authentication  system,  any  existing  sessions  will  be  invalidated  when  you 
upgrade  to  Laravel  5.2. 

Database  Session  Driver 

A new  database  session  driver  has  been  written  for  the  framework  which  includes  more  information 
about  the  user  such  as  their  user  ID,  IP  address,  and  user-agent.  If  you  would  like  to  continue  using 
the  old  driver  you  may  specify  the  legacy-database  driver  in  your  session  . php  configuration  file. 

If  you  would  like  to  use  the  new  driver,  you  should  add  the  user_id  (nullable  integer),  ip_- 
address  (nullable  string),  and  user_agent  ( text ) columns  to  your  session  database  table. 

Stringy 

The  “Stringy”  library  is  no  longer  included  with  the  framework.  You  may  install  it  manually  via 
Composer  if  you  wish  to  use  it  in  your  application. 
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Validation 

Exception  Types 

The  Val  idatesRequests  trait  now  throws  an  instance  of  1 1 luminate\Foundation\Val  idation\Val  idationExcepti 
instead  of  throwing  an  instance  of  Illuminate\Http\Exception\HttpResponseException.  This  is 
unlikely  to  affect  your  application  unless  you  were  manually  catching  this  exception. 

Deprecations 

The  following  features  are  deprecated  in  5.2  and  will  be  removed  in  the  5.3  release  in  June  2016: 

• 1 1 luminate\Contracts\Bus\Sel  fHandl  ing  contract.  Can  be  removed  from  jobs. 

• The  lists  method  on  the  Collection,  query  builder  and  Eloquent  query  builder  objects  has 
been  renamed  to  pluck.  The  method  signature  remains  the  same. 

• Implicit  controller  routes  using  Route : : controller  have  been  deprecated.  Please  use  explicit 
route  registration  in  your  routes  file.  This  will  likely  be  extracted  into  a package. 

• The  get,  post,  and  other  route  helper  functions  have  been  removed.  You  may  use  the  Route 
facade  instead. 

• The  database  session  driver  from  5.1  has  been  renamed  to  legacy-database  and  will  be 
removed.  Consult  notes  on  the  “database  session  driver”  above  for  more  information. 

• The  Str : : randomBytes  function  has  been  deprecated  in  favor  of  the  random_bytes  native  PHP 
function. 

• The  Str:  : equals  function  has  been  deprecated  in  favor  of  the  hash_equals  native  PHP 
function. 

• 1 1 luminate\View\Expression  has  been  deprecated  in  favor  of  1 1 luminate\Support\HtmlString. 


Upgrading  To  5.1.11  {#upgrade-upgrade-5.1.11} 

Laravel  5.1.11  includes  support  for  authorization  and  policies.  Incorporating  these  new  features  into 
your  existing  Laravel  5.1  applications  is  simple. 


Note:  These  upgrades  are  optional,  and  ignoring  them  will  not  affect  your  application. 


Create  The  Policies  Directory 

First,  create  an  empty  app/Pol  icies  directory  within  your  application. 
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Create  / Register  The  AuthServiceProvider  & Gate  Facade 

Create  a AuthServiceProvider  within  your  app/Providers  directory.  You  may  copy  the  contents 
of  the  default  provider  from  GitHub15.  Remember  to  change  the  provider’s  namespace  if  your 
application  is  using  a custom  namespace.  After  creating  the  provider,  be  sure  to  register  it  in  your 
app.php  configuration  file’s  providers  array. 

Also,  you  should  register  the  Gate  facade  in  your  app . php  configuration  file’s  aliases  array: 


1 'Gate'  =>  1 1 luminate\Support\Facades\Gate : :class, 


Update  The  User  Model 

Secondly,  use  the  1 1 luminate\Foundation\Auth\Access\Authorizable  trait  and  1 1 luminate\Contracts\Auth\Acc 
contract  on  your  App\User  model: 

1 < ?php 

2 

3 namespace  App; 

4 

5 use  1 1 luminate\Auth\Authenticatable; 

6 use  1 1 luminate\Database\Eloquent\Model ; 

7 use  1 1 luminate\Auth\Passwords\CanResetPassword; 

8 use  1 1 luminate\Foundation\Auth\Access\Author izable; 

9 use  1 1 luminate\Contracts\Auth\Authenticatable  as  AuthenticatableContract; 

10  use  1 1 luminate\Contracts\Auth\Access\Authorizable  as  Author izableContract; 

11  use  1 1 luminate\Contracts\Auth\CanResetPassword  as  CanResetPasswordContract; 

12 

13  class  User  extends  Model  implements  AuthenticatableContract, 

14  AuthorizableContract, 

15  CanResetPasswordContract 

16  { 

17  use  Authenticatable,  Authorizable,  CanResetPassword; 

18  } 


Update  The  Base  Controller 

Next,  update  your  base  App \Http\Control  lers\Control  ler  controller  to  use  the  1 1 luminate\Foundation\Auth\Acc 
trait: 

15https://raw.githubusercontent.com/laravel/laravel/master/app/Providers/AuthServiceProvider.php 
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1 < ?php 

2 

3 namespace  App\Http\Control lers; 

4 

5 use  1 1 luminate\Foundation\Bus\DispatchesJobs; 

6 use  1 1 luminate\Routing\Control ler  as  BaseControl ler ; 

7 use  Illuminate\Foundation\Validation\ValidatesRequests; 

8 use  Illuminate\Foundation\Auth\Access\AuthorizesRequests; 

9 

10  abstract  class  Controller  extends  BaseControl ler 

11  { 

use  AuthorizesRequests,  DispatchesJobs,  Val idatesRequests; 

13  } 


Upgrading  To  5.1.0  {#upgrade-upgrade-5.1.0} 

Estimated  Upgrade  Time:  Less  Than  1 Hour 

Update  bootstrap/autoload . php 

Update  the  $compi  ledPath  variable  in  bootstrap/autoload . php  to  the  following: 
1 $compi ledPath  = DIR . ' /cache/compi led . php ' ; 


Create  bootstrap/cache  Directory 

Within  your  bootstrap  directory,  create  a cache  directory  (bootstrap/cache).  Place  a .gitignore 
file  in  this  directory  with  the  following  contents: 


1 * 

2 ! . gitignore 


This  directory  should  be  writable,  and  will  be  used  by  the  framework  to  store  temporary  optimiza- 
tion files  like  compiled  . php,  routes . php,  conf ig . php,  and  services . json. 
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Add  BroadcastServiceProvider  Provider 

Within  your  con  fig/app . php  configuration  file,  add  1 1 luminate\Broadcasting\BroadcastServiceProvider 
to  the  providers  array. 


Authentication 

If  you  are  using  the  provided  AuthControl  ler  which  uses  the  AuthenticatesAndRegistersUsers 
trait,  you  will  need  to  make  a few  changes  to  how  new  users  are  validated  and  created. 

First,  you  no  longer  need  to  pass  the  Guard  and  Registrar  instances  to  the  base  constructor.  You  can 
remove  these  dependencies  entirely  from  your  controller’s  constructor. 

Secondly,  the  App\Services\Registrar  class  used  in  Laravel  5.0  is  no  longer  needed.  You  can 
simply  copy  and  paste  your  validator  and  create  method  from  this  class  directly  into  your 
AuthControl  ler.  No  other  changes  should  need  to  be  made  to  these  methods;  however,  you  should 
be  sure  to  import  the  Validator  facade  and  your  User  model  at  the  top  of  your  AuthControl  ler. 

Password  Controller 

The  included  PasswordControl  ler  no  longer  requires  any  dependencies  in  its  constructor.  You  may 
remove  both  of  the  dependencies  that  were  required  under  5.0. 


Validation 

If  you  are  overriding  the  formatVal  idationErrors  method  on  your  base  controller  class,  you  should 
now  type-hint  the  Illuminate\Contracts\Validation\Validator  contract  instead  of  the  concrete 
1 1 luminate\Val idation\Val idator  instance. 

Likewise,  if  you  are  overriding  the  formatErrors  method  on  the  base  form  request  class,  you  should 
now  type-hint  1 1 luminate\Contracts\Val idation\Val idator  contract  instead  of  the  concrete 
1 1 luminate\Val idation\Val idator  instance. 

Eloquent 

The  create  Method 

Eloquent’s  create  method  can  now  be  called  without  any  parameters.  If  you  are  overriding  the 
create  method  in  your  own  models,  set  the  default  value  of  the  $attr  ibutes  parameter  to  an  array: 
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1 public  static  function  create(array  $attributes  = []) 

2 { 

//  Your  custom  implementation 

4 } 


The  find  Method 

If  you  are  overriding  the  find  method  in  your  own  models  and  calling  parent : : f ind( ) within  your 
custom  method,  you  should  now  change  it  to  call  the  find  method  on  the  Eloquent  query  builder: 

1 public  static  function  find($id,  $columns  = ['*']) 

2 { 

$model  = static :: query( )-> find($id , Scolumns); 

4 

5 //  ... 

6 

return  $model; 

8 } 


The  lists  Method 

The  lists  method  now  returns  a Col  lection  instance  instead  of  a plain  array  for  Eloquent  queries. 
If  you  would  like  to  convert  the  Collection  into  a plain  array,  use  the  all  method: 

1 User : : 1 ists( ' id ' )->all( ) ; 


Be  aware  that  the  Query  Builder  lists  method  still  returns  an  array. 

Date  Formatting 

Previously,  the  storage  format  for  Eloquent  date  fields  could  be  modified  by  overriding  the 
getDateFormat  method  on  your  model.  This  is  still  possible;  however,  for  convenience  you  may 
simply  specify  a SdateFormat  property  on  the  model  instead  of  overriding  the  method. 

The  date  format  is  also  now  applied  when  serializing  a model  to  an  array  or  JSON.  This  may  change 
the  format  of  your  JSON  serialized  date  fields  when  migrating  from  Laravel  5.0  to  5.1.  To  set  a specific 
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date  format  for  serialized  models,  you  may  override  the  serial  izeDate(DateTime  $date)  method 
on  your  model.  This  method  allows  you  to  have  granular  control  over  the  formatting  of  serialized 
Eloquent  date  fields  without  changing  their  storage  format. 


The  Collection  Class 

The  sort  Method 

The  sort  method  now  returns  a fresh  collection  instance  instead  of  modifying  the  existing  collection: 

1 $collection  = $collection->sort($callback); 


The  sortBy  Method 

The  sortBy  method  now  returns  a fresh  collection  instance  instead  of  modifying  the  existing 
collection: 

1 $col lection  = $col lection- >sortBy( ' name  1 ) ; 


The  groupBy  Method 

The  groupBy  method  now  returns  Col  lection  instances  for  each  item  in  the  parent  Collection.  If 
you  would  like  to  convert  all  of  the  items  back  to  plain  arrays,  you  may  map  over  them: 


1 $col lection- >groupBy( 'type' ) ->map( function($item) 

2 { 

return  $item->al 1 ( ) ; 

4 }); 


The  lists  Method 

The  lists  method  now  returns  a Collection  instance  instead  of  a plain  array.  If  you  would  like  to 
convert  the  Col  lection  into  a plain  array,  use  the  all  method: 
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1 $col lection- > 1 ists( 'id')->all(); 


Commands  & Handlers 

The  app/Commands  directory  has  been  renamed  to  app/Jobs.  However,  you  are  not  required  to  move 
all  of  your  commands  to  the  new  location,  and  you  may  continue  using  the  make: command  and 
handler : command  Artisan  commands  to  generate  your  classes. 

Likewise,  the  app/Handlers  directory  has  been  renamed  to  app/Listeners  and  now  only  contains 
event  listeners.  However,  you  are  not  required  to  move  or  rename  your  existing  command  and  event 
handlers,  and  you  may  continue  to  use  the  handler : event  command  to  generate  event  handlers. 

By  providing  backwards  compatibility  for  the  Laravel  5.0  folder  structure,  you  may  upgrade  your 
applications  to  Laravel  5.1  and  slowly  upgrade  your  events  and  commands  to  their  new  locations 
when  it  is  convenient  for  you  or  your  team. 


Blade 

The  createMatcher,  createOpenMatcher,  and  createPlainMatcher  methods  have  been  removed 
from  the  Blade  compiler.  Lise  the  new  directive  method  to  create  custom  directives  for  Blade  in 
Laravel  5.1.  Consult  the  extending  blade  documentation  for  more  information. 


Tests 

Add  the  protected  SbaseUrl  property  to  the  tests/TestCase . php  file: 
1 protected  SbaseUrl  = ' http : //localhost ' ; 


Translation  Files 

The  default  directory  for  published  language  files  for  vendor  packages  has  been  moved.  Move 
any  vendor  package  language  files  from  resources/lang/packages/{locale}/{namespace}  to 
resources/lang/vendor/{namespace}/{ locale}  directory.  For  example,  Acme/Anvil  package’s 
acme/anvil : : foo  namespaced  English  language  file  would  be  moved  from  resources/ lang/pack- 
ages/en/acme/anvi 1/foo . php  to  resources/lang/vendor/acme/anvi 1/en/foo . php. 
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Amazon  Web  Services  SDK 

If  you  are  using  the  AWS  SQS  queue  driver  or  the  AWS  SES  e-mail  driver,  you  should  update  your 
installed  AWS  PHP  SDK  to  version  3.0. 

If  you  are  using  the  Amazon  S3  filesystem  driver,  you  will  need  to  update  the  corresponding 
Flysystem  package  via  Composer: 

• Amazon  S3:  league/f Iysystem-aws-s3-v3  ~1.0 

Deprecations 

The  following  Laravel  features  have  been  deprecated  and  will  be  removed  entirely  with  the  release 
of  Laravel  5.2  in  December  2015: 

<div  class=”content-list”  markdown=’T”>  - Route  filters  have  been  deprecated  in  preference  of 
middleware.  - The  Illuminate\Contracts\Routing\Middleware  contract  has  been  deprecated. 
No  contract  is  required  on  your  middleware.  In  addition,  the  TerminableMiddleware  contract 
has  also  been  deprecated.  Instead  of  implementing  the  interface,  simply  define  a terminate 
method  on  your  middleware.  - The  1 1 luminate\Contracts\Queue\ShouldBeQueued  contract  has 
been  deprecated  in  favor  of  1 1 luminate\Contracts\Queue\ShouldQueue.  - Iron.io  “push  queues” 
have  been  deprecated  in  favor  of  typical  Iron.io  queues  and  queue  listeners.  - The  Illumi- 
nate\Foundation\Bus\DispatchesCommands  trait  has  been  deprecated  and  renamed  to  Illumi- 
nate\Foundation\Bus\DispatchesJobs.  - 1 1 luminate\Container\BindingResolutionException 
has  been  moved  to  1 1 luminate\Contracts\Container\BindingResolutionException.  - The  service 
container’s  bindShared  method  has  been  deprecated  in  favor  of  the  singleton  method.  - The 
Eloquent  and  query  builder  pluck  method  has  been  deprecated  and  renamed  to  value.  - The 
collection  fetch  method  has  been  deprecated  in  favor  of  the  pluck  method.  - The  array_fetch 
helper  has  been  deprecated  in  favor  of  the  array_pluck  method.  </div> 

Upgrading  To  5.0.16  {#upgrade-upgrade-5.0.16} 


In  your  bootstrap/autoload  . php  file,  update  the  $compi  ledPath  variable  to: 


1 $compi ledPath  = DIR . ' / . . /vendor/compi led . php ' ; 


Service  Providers 

The  App\Providers\BusServiceProvider  may  be  removed  from  your  service  provider  list  in  your 
app . php  configuration  file. 
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The  App\Providers\Conf  igServiceProvider  may  be  removed  from  your  service  provider  list  in 
your  app . php  configuration  file. 

Upgrading  To  5.0  From  4.2  {#upgrade-upgrade-5.0} 

Fresh  Install,  Then  Migrate 

The  recommended  method  of  upgrading  is  to  create  a new  Laravel  5 . 0 install  and  then  to  copy  your 
4 . 2 site’s  unique  application  files  into  the  new  application.  This  would  include  controllers,  routes, 
Eloquent  models,  Artisan  commands,  assets,  and  other  code  specific  files  to  your  application. 

To  start,  install  a new  Laravel  5.0  application  into  a fresh  directory  in  your  local  environment.  Do 
not  install  any  versions  newer  than  5.0  yet,  since  we  need  to  complete  the  migration  steps  for  5.0 
first.  We’ll  discuss  each  piece  of  the  migration  process  in  further  detail  below. 

Composer  Dependencies  & Packages 

Don’t  forget  to  copy  any  additional  Composer  dependencies  into  your  5.0  application.  This  includes 
third-party  code  such  as  SDKs. 

Some  Laravel-specific  packages  may  not  be  compatible  with  Laravel  5 on  initial  release.  Check  with 
your  package’s  maintainer  to  determine  the  proper  version  of  the  package  for  Laravel  5.  Once  you 
have  added  any  additional  Composer  dependencies  your  application  needs,  run  composer  update. 

Namespacing 

By  default,  Laravel  4 applications  did  not  utilize  namespacing  within  your  application  code.  So,  for 
example,  all  Eloquent  models  and  controllers  simply  lived  in  the  “global”  namespace.  Lor  a quicker 
migration,  you  can  simply  leave  these  classes  in  the  global  namespace  in  Laravel  5 as  well. 

Configuration 

Migrating  Environment  Variables 

Copy  the  new  . env.  example  file  to  . env,  which  is  the  5.0  equivalent  of  the  old  .env.php  file.  Set 
any  appropriate  values  there,  like  your  APP_ENV  and  APP_KEY  (your  encryption  key),  your  database 
credentials,  and  your  cache  and  session  drivers. 

Additionally,  copy  any  custom  values  you  had  in  your  old  .env.php  file  and  place  them  in  both 
. env  (the  real  value  for  your  local  environment)  and  . env . example  (a  sample  instructional  value  for 
other  team  members). 

Lor  more  information  on  environment  configuration,  view  the  full  documentation. 
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Configuration  Files 

Laravel  5.0  no  longer  uses  app/conf ig/{environmentName}/  directories  to  provide  specific  con- 
figuration files  for  a given  environment.  Instead,  move  any  configuration  values  that  vary  by 
environment  into  .env,  and  then  access  them  in  your  configuration  files  using  env  ( 'key' , 'default 
value' ).  You  will  see  examples  of  this  in  the  config/database.php  configuration  file. 

Set  the  config  files  in  the  con  fig/  directory  to  represent  either  the  values  that  are  consistent  across 
all  of  your  environments,  or  set  them  to  use  env( ) to  load  values  that  vary  by  environment. 

Remember,  if  you  add  more  keys  to  .env  file,  add  sample  values  to  the  .env.  example  file  as  well. 
This  will  help  your  other  team  members  create  their  own  . env  files. 


Routes 

Copy  and  paste  your  old  routes . php  file  into  your  new  app/Http/routes . php. 


Controllers 

Next,  move  all  of  your  controllers  into  the  app/Http/Control  lers  directory.  Since  we  are  not 
going  to  migrate  to  full  namespacing  in  this  guide,  add  the  app/Http/Control  lers  directory  to 
the  classmap  directive  of  your  composer . json  file.  Next,  you  can  remove  the  namespace  from  the 
abstract  app/Http/Control  lers/Control  ler  .php  base  class.  Verify  that  your  migrated  controllers 
are  extending  this  base  class. 

In  your  app/Providers/RouteServiceProvider . php  file,  set  the  namespace  property  to  null. 


Route  Filters 

Copy  your  filter  bindings  from  app/fi  Iters . php  and  place  them  into  the  boot()  method  of  ap- 
p/Providers/RouteServiceProvider . php.  Add  use  1 1 luminate\Support\Facades\Route;  in  the 
app/Providers/RouteServiceProvider . php  in  order  to  continue  using  the  Route  Facade. 

You  do  not  need  to  move  over  any  of  the  default  Laravel  4.0  filters  such  as  auth  and  csrf;  they’re 
all  here,  but  as  middleware.  Edit  any  routes  or  controllers  that  reference  the  old  default  filters  (e.g. 
['before'  =>  ' auth  '])  and  change  them  to  reference  the  new  middleware  (e.g.  ['  middleware ' => 

' auth ' ] . ) 

Filters  are  not  removed  in  Laravel  5.  You  can  still  bind  and  use  your  own  custom  filters  using  before 
and  after. 
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Global  CSRF 

By  default,  CSRF  protection  is  enabled  on  all  routes.  If  you’d  like  to  disable  this,  or  only  manually 
enable  it  on  certain  routes,  remove  this  line  from  App\Http\Kernel  ’s  middleware  array: 

1 ' App\Http\Middleware\Ver i fyCsrfToken ' , 

If  you  want  to  use  it  elsewhere,  add  this  line  to  $routeMiddleware: 

1 'csrf'  =>  ' App\Http\Middleware\Ver i fyCsrfToken ' , 


Now  you  can  add  the  middleware  to  individual  routes  / controllers  using  ['middleware'  => 

' csr  f ' ] on  the  route.  For  more  information  on  middleware,  consult  the  full  documentation. 

Eloquent  Models 

Feel  free  to  create  a new  app/Models  directory  to  house  your  Eloquent  models.  Again,  add  this 
directory  to  the  classmap  directive  of  your  composer . json  file. 

Update  any  models  using  SoftDeletingTra  it  to  use  1 1 luminate\Database\Eloquent\SoftDeletes. 


Eloquent  Caching 

Eloquent  no  longer  provides  the  remember  method  for  caching  queries.  You  now  are  responsible 
for  caching  your  queries  manually  using  the  Cache:  : remember  function.  For  more  information  on 
caching,  consult  the  full  documentation. 


User  Authentication  Model 

To  upgrade  your  User  model  for  Laravel  5’s  authentication  system,  follow  these  instructions: 

Delete  the  following  from  your  use  block: 

1 use  1 1 luminate\Auth\User Interface; 

2 use  1 1 luminate\Auth\Reminders\RemindableInterface; 


Add  the  following  to  your  use  block: 
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1 use  Illuminate \Auth\Authenticatable; 

2 use  Illuminate \Auth\Passwords\CanResetPassword; 

3 use  1 1 luminate\Contracts\Auth\Authenticatable  as  AuthenticatableContract; 

4 use  1 1 luminate\Contracts\Auth\CanResetPassword  as  CanResetPasswordContract; 

Remove  the  Userlnterface  and  Remindablelnterface  interfaces. 

Mark  the  class  as  implementing  the  following  interfaces: 

1 implements  AuthenticatableContract,  CanResetPasswordContract 

Include  the  following  traits  within  the  class  declaration: 

1 use  Authenticatable,  CanResetPassword; 


If  you  used  them,  remove  Illuminate\Auth\Reminders\RemindableTrait  and  Illuminate\Auth\UserTrait 
from  your  use  block  and  your  class  declaration. 

Cashier  User  Changes 

The  name  of  the  trait  and  interface  used  by  Laravel  Cashier  has  changed.  Instead  of  using  Bi  1 lable - 
Trait,  use  the  Laravel  \Cashier\Bi  1 lable  trait.  And,  instead  of  Laravel  \Cashier\Bi  1 lablelnterface 
implement  the  Laravel  \Cashier\Contracts\Bi  1 lable  interface  instead.  No  other  method  changes 
are  required. 


Artisan  Commands 

Move  all  of  your  command  classes  from  your  old  app/commands  directory  to  the  new  app/Con- 
sole/Commands  directory.  Next,  add  the  app/Console/Commands  directory  to  the  classmap  directive 
of  your  composer . json  file. 

Then,  copy  your  list  of  Artisan  commands  from  start/artisan . php  into  the  command  array  of  the 
app/Console/Kernel . php  file. 

Database  Migrations  & Seeds 

Delete  the  two  migrations  included  with  Laravel  5.0,  since  you  should  already  have  the  users  table 
in  your  database. 

Move  all  of  your  migration  classes  from  the  old  app/database/migrations  directory  to  the 
new  database/migrations.  All  of  your  seeds  should  be  moved  from  app/database/seeds  to 
database/seeds. 
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Global  loC  Bindings 

If  you  have  any  service  container  bindings  in  start/global  .php,  move  them  all  to  the  register 
method  of  the  app/Providers/AppServiceProvider . php  file.  You  may  need  to  import  the  App 
facade. 

Optionally,  you  may  break  these  bindings  up  into  separate  service  providers  by  category. 


Views 

Move  your  views  from  app/views  to  the  new  resources/views  directory. 

Blade  Tag  Changes 

For  better  security  by  default,  Laravel  5.0  escapes  all  output  from  both  the  { { } } and  { { { } } } Blade 
directives.  A new  { ! ! ! ! } directive  has  been  introduced  to  display  raw,  unescaped  output.  The  most 
secure  option  when  upgrading  your  application  is  to  only  use  the  new  { ! ! ! ! } directive  when  you 
are  certain  that  it  is  safe  to  display  raw  output. 

However,  if  you  must  use  the  old  Blade  syntax,  add  the  following  lines  at  the  bottom  of  AppServi - 
ceProvider@register: 


1 \Blade : : setRawTags( ' { { ' , '}}'); 

2 \Blade : : setContentTags( ' { { { ' , '}}}'); 

3 \Blade : : setEscapedContentTags( ' { { { 1 , '}}}'); 

This  should  not  be  done  lightly,  and  may  make  your  application  more  vulnerable  to  XSS  exploits. 
Also,  comments  with  { { - - will  no  longer  work. 

Translation  Files 

Move  your  language  files  from  app/lang  to  the  new  resources/ lang  directory. 

Public  Directory 

Copy  your  application’s  public  assets  from  your  4.2  application’s  public  directory  to  your  new 
application’s  public  directory.  Be  sure  to  keep  the  5 . 0 version  of  index . php. 


Tests 


Move  your  tests  from  app/tests  to  the  new  tests  directory. 
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Misc.  Files 

Copy  in  any  other  files  in  your  project.  For  example,  . scrutinizer .yml,  bower,  json  and  other 
similar  tooling  configuration  files. 

You  may  move  your  Sass,  Less,  or  CoffeeScript  to  any  location  you  wish.  The  resources/assets 
directory  could  be  a good  default  location. 

Form  & HTML  Helpers 

If  you’re  using  Form  or  HTML  helpers,  you  will  see  an  error  stating  class  'Form'  not  found 
or  class  'Html ' not  found.  The  Form  and  HTML  helpers  have  been  deprecated  in  Laravel  5.0; 
however,  there  are  community-driven  replacements  such  as  those  maintained  by  the  Laravel 
Collective16. 

For  example,  you  may  add  "laravelcollective/html" : "~5.0"  to  your  composer . json  file’s 
require  section. 

You’ll  also  need  to  add  the  Form  and  HTML  facades  and  service  provider.  Edit  conf  ig/app . php  and 
add  this  line  to  the  ‘providers’  array: 

1 'Collective\Html\HtmlServiceProvider ' , 


Next,  add  these  lines  to  the  ‘aliases’  array: 


1 'Form'  =>  ' Col lective\Html \FormFacade ' , 

2 'Html'  =>  ' Col lective\Html \HtmlFacade 1 , 


CacheManager 

If  your  application  code  was  injecting  1 1 luminate\Cache\CacheManager  to  get  a non-Facade  version 
of  Laravel’s  cache,  inject  Illuminate\Contracts\Cache\Repository  instead. 

Pagination 

Replace  any  calls  to  $paginator->links( ) with  $paginator- > render ( ). 

16http://laravelcollective.com/docs/\protect\char”007B\relax\protect\char”007B\relaxversion\protect\char”007D\relax\protect\char”007D\relax/ 

html 
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Replace  any  calls  to  $paginator-  >getFrom( ) and$paginator-  >getTo( ) with$paginator-  > f irstltem( ) 
and  $paginator->  lastltem( ) respectively. 

Remove  the  “get”  prefix  from  calls  to  $pag  i nator  - > getPer Page  ( ) , $pag  i nator  - > getCurrentPage  ( ) , 
$paginator- >getLastPage( ) and  $paginator- >getTotal ( ) (e.g.  $paginator->perPage( )). 

Beanstalk  Queuing 

Laravel  5.0  now  requires  "pda/pheanstalk" : "~3.0"  instead  of  "pda/pheanstalk" : "~2.1". 

Remote 

The  Remote  component  has  been  deprecated. 

Workbench 

The  Workbench  component  has  been  deprecated. 

Upgrading  To  4.2  From  4.1 

PHP5.4+ 

Laravel  4.2  requires  PHP  5.4.0  or  greater. 

Encryption  Defaults 

Add  a new  cipher  option  in  your  app/conf  ig/app . php  configuration  file.  The  value  of  this  option 
should  be  MCRYPT_RI  JNDAEL_256. 

1 'cipher'  =>  MCRYPT_RI JNDAEL_256 


This  setting  may  be  used  to  control  the  default  cipher  used  by  the  Laravel  encryption  facilities. 


Note:  In  Laravel  4.2,  the  default  cipher  is  MCRYPT_RI  JNDAEL_128  (AES),  which  is  considered 
to  be  the  most  secure  cipher.  Changing  the  cipher  back  to  MCRYPT_RI  JNDAEL_256  is  required 
to  decrypt  cookies/values  that  were  encrypted  in  Laravel  <=  4.1 
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Soft  Deleting  Models  Now  Use  Traits 

If  you  are  using  soft  deleting  models,  the  softDeletes  property  has  been  removed.  You  must  now 
use  the  SoftDeletingTrait  like  so: 


1 use  1 1 luminate\Database\Eloquent\SoftDeletingTrait; 

2 

3 class  User  extends  Eloquent 

4 { 

5 use  SoftDeletingTrait; 

6 } 


You  must  also  manually  add  the  deleted_at  column  to  your  dates  property: 


1 class  User  extends  Eloquent 

2 { 

use  SoftDeletingTrait; 

4 

protected  $dates  = [ ' deleted_at ' ] ; 

6 } 


The  API  for  all  soft  delete  operations  remains  the  same. 

Note:  The  SoftDeletingTrait  can  not  be  applied  on  a base  model.  It  must  be  used  on  an 
actual  model  class. 


View  / Pagination  Environment  Renamed 

If  you  are  directly  referencing  the  1 1 luminate\View\Environment  class  or  1 1 luminate \Pagi  nation  \Environment 
class,  update  your  code  to  reference  1 1 luminate\View\Factory  and  1 1 lumi  nate\Pagi  nation \Factory 
instead.  These  two  classes  have  been  renamed  to  better  reflect  their  function. 

Additional  Parameter  On  Pagination  Presenter 

If  you  are  extending  the  Illuminate\Pagination\Presenter  class,  the  abstract  method  get- 
PageLinkWrapper  signature  has  changed  to  add  the  rel  argument: 
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1 abstract  public  function  getPageLinkWrapper($ur 1 , $page,  $rel  = null); 


Iron.lo  Queue  Encryption 

If  you  are  using  the  Iron.io  queue  driver,  you  will  need  to  add  a new  encrypt  option  to  your  queue 
configuration  file: 

1 'encrypt'  =>  true 


Upgrading  To  4.1.29  From  <=  4.1.x 

Laravel  4.1.29  improves  the  column  quoting  for  all  database  drivers.  This  protects  your  application 
from  some  mass  assignment  vulnerabilities  when  not  using  the  tillable  property  on  models.  If  you 
are  using  the  tillable  property  on  your  models  to  protect  against  mass  assignment,  your  application 
is  not  vulnerable.  However,  if  you  are  using  guarded  and  are  passing  a user  controlled  array  into 
an  “update”  or  “save”  type  function,  you  should  upgrade  to  4 . 1 . 29  immediately  as  your  application 
may  be  at  risk  of  mass  assignment. 

To  upgrade  to  Laravel  4.1.29,  simply  composer  update.  No  breaking  changes  are  introduced  in  this 
release. 

Upgrading  To  4.1.26  From  <=  4.1.25 


Laravel  4.1.26  introduces  security  improvements  for  “remember  me”  cookies.  Before  this  update,  if  a 
remember  cookie  was  hijacked  by  another  malicious  user,  the  cookie  would  remain  valid  for  a long 
period  of  time,  even  after  the  true  owner  of  the  account  reset  their  password,  logged  out,  etc. 

This  change  requires  the  addition  of  a new  remember_token  column  to  your  users  (or  equivalent) 
database  table.  After  this  change,  a fresh  token  will  be  assigned  to  the  user  each  time  they  login  to 
your  application.  The  token  will  also  be  refreshed  when  the  user  logs  out  of  the  application.  The 
implications  of  this  change  are:  if  a “remember  me”  cookie  is  hijacked,  simply  logging  out  of  the 
application  will  invalidate  the  cookie. 

Upgrade  Path 

First,  add  a new,  nullable  remember_token  of  VARCHAR(lOO),  TEXT,  or  equivalent  to  your  users 
table. 
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Next,  if  you  are  using  the  Eloquent  authentication  driver,  update  your  User  class  with  the  following 
three  methods: 


1 public  function  getRememberToken( ) 

2 { 

return  $this->remember_token; 

4 } 

5 

6 public  function  setRememberToken(lvalue) 

7 { 

$this- >remember_token  = $value; 

9 } 

10 

11  public  function  getRememberTokenName( ) 

12  { 

return  ' remember_token ' ; 

14  } 


Note:  All  existing  “remember  me”  sessions  will  be  invalidated  by  this  change,  so  all  users 
will  be  forced  to  re-authenticate  with  your  application. 


Package  Maintainers 

Two  new  methods  were  added  to  the  1 1 luminate\Auth\UserProvider Interface  interface.  Sample 
implementations  may  be  found  in  the  default  drivers: 


1 public  function  retrieveByToken($identi f ier , $token); 

2 

3  public  function  updateRememberToken( User  Inter  face  $user,  $token); 


The  1 1 luminate\Auth\UserInterface  also  received  the  three  new  methods  described  in  the 
“Upgrade  Path”. 
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Upgrading  To  4.1  From  4.0 

Upgrading  Your  Composer  Dependency 

To  upgrade  your  application  to  Laravel  4.1,  change  your  laravel/framework  version  to  4.1 . * in 
your  composer . json  file. 

Replacing  Files 

Replace  your  publ  ic/ index . php  file  with  this  fresh  copy  from  the  repository17. 

Replace  your  artisan  file  with  this  fresh  copy  from  the  repository18. 

Adding  Configuration  Files  & Options 

Update  your  aliases  and  providers  arrays  in  your  app/conf  ig/app . php  configuration  fde.  The 
updated  values  for  these  arrays  can  be  found  in  this  file19.  Be  sure  to  add  your  custom  and  package 
service  providers  / aliases  back  to  the  arrays. 

Add  the  new  app/conf  ig/remote . php  file  from  the  repository20. 

Add  the  new  exp ire_on_c lose  configuration  option  to  your  app/conf  ig/session . php  file.  The 
default  value  should  be  false. 

Add  the  new  failed  configuration  section  to  your  app/conf  ig/queue . php  file.  Here  are  the  default 
values  for  the  section: 

1 'failed'  =>  [ 

'database'  =>  'mysql',  ’table'  =>  ' fai led_jobs ' , 

3 1, 


(Optional)  Update  the  pagination  configuration  option  in  your  app/conf ig/view. php  file  to 
pagination: :slider-3. 

Controller  Updates 

If  app/control lers/BaseControl ler . php  has  a use  statement  at  the  top,  change  use  Illumi- 
nate\Routing\Control lers\Control ler ; to  use  1 1 luminate\Routing\Control ler ; . 

1 7 https  ://github . com/laravel/laravel/blob/ v4 . 1 .0/public/ index,  php 
18https://github.com/laravel/laravel/blob/v4.1. 0/artisan 
1 9https  ://github . com/laravel/laravel/blob/ v4 . 1 . 0/app/config/app  .php 
20https://github.com/laravel/laravel/blob/v4.1.0/app/config/remote.php 
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Password  Reminders  Updates 

Password  reminders  have  been  overhauled  for  greater  flexibility.  You  may  examine  the  new  stub 
controller  by  running  the  php  artisan  auth  : reminders-control  ler  Artisan  command.  You  may 
also  browse  the  updated  documentation  and  update  your  application  accordingly. 

Update  your  app/lang/en/reminders . php  language  file  to  match  this  updated  file21. 

Environment  Detection  Updates 

For  security  reasons,  URL  domains  may  no  longer  be  used  to  detect  your  application  environment. 
These  values  are  easily  spoofable  and  allow  attackers  to  modify  the  environment  for  a request.  You 
should  convert  your  environment  detection  to  use  machine  host  names  (hostname  command  on 
Mac,  Linux,  and  Windows). 

Simpler  Log  Files 

Laravel  now  generates  a single  log  file:  app/storage/logs/laravel . log.  However,  you  may  still 
configure  this  behavior  in  your  app/start/global . php  file. 

Removing  Redirect  Trailing  Slash 

In  your  bootstrap/start.php  file,  remove  the  call  to  $app- >redirectl fTrai  1 ingSlash( ).  This 
method  is  no  longer  needed  as  this  functionality  is  now  handled  by  the  . htaccess  file  included 
with  the  framework. 

Next,  replace  your  Apache  . htaccess  file  with  this  new  one22  that  handles  trailing  slashes. 

Current  Route  Access 

The  current  route  is  now  accessed  via  Route:  :current( ) instead  of  Route:  : getCurrentRoute( ). 

Composer  Update 

Once  you  have  completed  the  changes  above,  you  can  run  the  composer  update  function  to  update 
your  core  application  files!  If  you  receive  class  load  errors,  try  running  the  update  command  with 
the  - -no-scripts  option  enabled  like  so:  composer  update  --no-scripts. 

Wildcard  Event  Listeners 

The  wildcard  event  listeners  no  longer  append  the  event  to  your  handler  functions  parameters.  If 
you  require  finding  the  event  that  was  fired  you  should  use  Event:  : firing ( ). 

21https://github.com/laravel/laravel/blob/v4.1.0/app/lang/en/reminders.php 

22https://github.com/laravel/laravel/blob/v4.1.0/public/.htaccess 
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Bug  Reports 

To  encourage  active  collaboration,  Laravel  strongly  encourages  pull  requests,  not  just  bug  reports. 
“Bug  reports”  may  also  be  sent  in  the  form  of  a pull  request  containing  a failing  test. 

However,  if  you  fde  a bug  report,  your  issue  should  contain  a title  and  a clear  description  of  the 
issue.  You  should  also  include  as  much  relevant  information  as  possible  and  a code  sample  that 
demonstrates  the  issue.  The  goal  of  a bug  report  is  to  make  it  easy  for  yourself  - and  others  - to 
replicate  the  bug  and  develop  a fix. 

Remember,  bug  reports  are  created  in  the  hope  that  others  with  the  same  problem  will  be  able  to 
collaborate  with  you  on  solving  it.  Do  not  expect  that  the  bug  report  will  automatically  see  any 
activity  or  that  others  will  jump  to  fix  it.  Creating  a bug  report  serves  to  help  yourself  and  others 
start  on  the  path  of  fixing  the  problem. 

The  Laravel  source  code  is  managed  on  Github,  and  there  are  repositories  for  each  of  the  Laravel 
projects: 

• Laravel  Framework23 

• Laravel  Application24 

• Laravel  Documentation25 

• Laravel  Cashier26 

• Laravel  Envoy27 

• Laravel  Homestead28 

• Laravel  Homestead  Build  Scripts29 

2 3https  ://github . com/laravel/framework 
2 4https :/ /github . com/laravel/laravel 
25https://github.com/laravel/docs 
2 6https  ://github . com/laravel/cashier 
27https://github.com/laravel/envoy 
2 8https  ://github . com/laravel/homestead 
2 9https :/ /github . com/laravel/settler 
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• Laravel  Website30 

• Laravel  Art31 

Core  Development  Discussion 

Discussion  regarding  bugs,  new  features,  and  implementation  of  existing  features  takes  place  in 
the  # interna  Is  channel  of  the  LaraChat32  Slack  team.  Taylor  Otwell,  the  maintainer  of  Laravel,  is 
typically  present  in  the  channel  on  weekdays  from  8am-5pm  (UTC-06:00  or  America/Chicago),  and 
sporadically  present  in  the  channel  at  other  times. 


Which  Branch? 


All  bug  fixes  should  be  sent  to  the  latest  stable  branch.  Bug  fixes  should  never  be  sent  to  the  master 
branch  unless  they  fix  features  that  exist  only  in  the  upcoming  release. 

Minor  features  that  are  fully  backwards  compatible  with  the  current  Laravel  release  may  be  sent 
to  the  latest  stable  branch. 

Major  new  features  should  always  be  sent  to  the  master  branch,  which  contains  the  upcoming 
Laravel  release. 

If  you  are  unsure  if  your  feature  qualifies  as  a major  or  minor,  please  ask  Taylor  Otwell  in  the 
# interna  Is  channel  of  the  LaraChat33  Slack  team. 

Security  Vulnerabilities 

If  you  discover  a security  vulnerability  within  Laravel,  please  send  an  e-mail  to  Taylor  Otwell  at 
<a  href=”mailto:taylor@laravel.com”>taylor@laravel.com</a>.  All  security  vulnerabilities  will  be 
promptly  addressed. 

Coding  Style 

Laravel  follows  the  PSR-234  coding  standard  and  the  PSR-435  autoloading  standard. 

30https://github.com/laravel/laravel.com 

31https://github.com/laravel/art 

32http://larachat.co 

33http://larachat.co 

34https  ://github . com/php-  fig/fig-  standards/blob/ master/accepted/PSR-  2 - coding-  style-  guide . md 
35https://github.com/php-fig/fig-standards/blob/master/accepted/PSR-4-autoloader.md 
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DocBlocks 

@param  tags  should  not  be  aligned  and  arguments  should  be  separated  by  2 spaces. 
Here’s  an  example  block: 

1 /** 

2 * Register  a binding  with  the  container . 

3 * 

4 * §param  string  I array  $abstract 

5 * §param  \Closure / string / nul 1 $concrete 

6 * @param  bool  $ shared 

7 * §return  void 

8 V 

9 public  function  bind($abstract,  Sconcrete  = null,  $shared  false) 

10  { 

11  // 

12  } 


Code  Style  Fixer 

You  may  use  the  PHP-CS-Fixer36  to  fix  your  code  style  before  committing. 

To  get  started,  install  the  tool  globally37  and  check  the  code  style  by  issuing  the  following  terminal 
command  from  your  project’s  root  directory: 


php-cs-fixer  fix 


36https://github.com/FriendsOfPHP/PHP-CS-Fixer 
37https://github.com/FriendsOfPHP/PHP-CS-Fixer#globally-  manual 
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Installation 

Server  Requirements 

The  Laravel  framework  has  a few  system  requirements.  Of  course,  all  of  these  requirements  are 
satisfied  by  the  Laravel  Homestead  virtual  machine,  so  it’s  highly  recommended  that  you  use 
Homestead  as  your  local  Laravel  development  environment. 

However,  if  you  are  not  using  Homestead,  you  will  need  to  make  sure  your  server  meets  the  following 
requirements: 

<div  class=”content-list”  markdown=’T”>  - PHP  >=  5.5.9  - OpenSSL  PHP  Extension  - PDO  PHP 
Extension  - Mbstring  PHP  Extension  - Tokenizer  PHP  Extension  </div> 

Installing  Laravel 

Laravel  utilizes  Composer38  to  manage  its  dependencies.  So,  before  using  Laravel,  make  sure  you 
have  Composer  installed  on  your  machine. 

Via  Laravel  Installer 

First,  download  the  Laravel  installer  using  Composer: 

1 composer  global  require  " laravel/instal ler" 


Make  sure  to  place  the  ~/ . composer/vendor/bin  directory  (or  the  equivalent  directory  for  your 
OS)  in  your  PATH  so  the  laravel  executable  can  be  located  by  your  system. 

Once  installed,  the  laravel  new  command  will  create  a fresh  Laravel  installation  in  the  directory 
you  specify.  For  instance,  laravel  new  blog  will  create  a directory  named  blog  containing  a fresh 
Laravel  installation  with  all  of  Laravel’s  dependencies  already  installed.  This  method  of  installation 
is  much  faster  than  installing  via  Composer: 


38http://getcomposer.org 
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1 laravel  new  blog 


Via  Composer  Create-Project 

Alternatively,  you  may  also  install  Laravel  by  issuing  the  Composer  create-project  command  in 
your  terminal: 

1 composer  create-project  - -prefer-dist  laravel/laravel  blog 


Configuration 

All  of  the  configuration  files  for  the  Laravel  framework  are  stored  in  the  con  fig  directory.  Each 
option  is  documented,  so  feel  free  to  look  through  the  files  and  get  familiar  with  the  options  available 
to  you. 

Directory  Permissions 

After  installing  Laravel,  you  may  need  to  configure  some  permissions.  Directories  within  the 
storage  and  the  bootstrap/cache  directories  should  be  writable  by  your  web  server  or  Laravel 
will  not  run.  If  you  are  using  the  Homestead  virtual  machine,  these  permissions  should  already  be 
set. 

Application  Key 

The  next  thing  you  should  do  after  installing  Laravel  is  set  your  application  key  to  a random  string. 
If  you  installed  Laravel  via  Composer  or  the  Laravel  installer,  this  key  has  already  been  set  for  you 
by  the  artisan  key: generate  command.  Typically,  this  string  should  be  32  characters  long.  The 
key  can  be  set  in  the  . env  environment  file.  If  you  have  not  renamed  the  . env . example  file  to  . env, 
you  should  do  that  now.  If  the  application  key  is  not  set,  your  user  sessions  and  other  encrypted 
data  will  not  be  secure! 

Additional  Configuration 

Laravel  needs  almost  no  other  configuration  out  of  the  box.  You  are  free  to  get  started  developing! 
However,  you  may  wish  to  review  the  conf  ig/app . php  file  and  its  documentation.  It  contains  several 
options  such  as  timezone  and  locale  that  you  may  wish  to  change  according  to  your  application. 

You  may  also  want  to  configure  a few  additional  components  of  Laravel,  such  as: 
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• Cache 

• Database 

• Session 


Once  Laravel  is  installed,  you  should  also  configure  your  local  environment. 


Configuration 

• Introduction 

• Accessing  Configuration  Values 

• Environment  Configuration  A>  - Determining  The  Current  Environment 

• Configuration  Caching 

• Maintenance  Mode 

Introduction 

All  of  the  configuration  files  for  the  Laravel  framework  are  stored  in  the  con  fig  directory.  Each 
option  is  documented,  so  feel  free  to  look  through  the  files  and  get  familiar  with  the  options  available 
to  you. 

Accessing  Configuration  Values 

You  may  easily  access  your  configuration  values  using  the  global  con  fig  helper  function  from 
anywhere  in  your  application.  The  configuration  values  may  be  accessed  using  “dot”  syntax,  which 
includes  the  name  of  the  file  and  option  you  wish  to  access.  A default  value  may  also  be  specified 
and  will  be  returned  if  the  configuration  option  does  not  exist: 


1 lvalue  = conf ig( ' app . timezone 1 ) ; 


To  set  configuration  values  at  runtime,  pass  an  array  to  the  conf  ig  helper: 
1 conf ig( [ 1 app . timezone 1 =>  'America/Chicago']); 


Environment  Configuration 

It  is  often  helpful  to  have  different  configuration  values  based  on  the  environment  the  application  is 
running  in.  For  example,  you  may  wish  to  use  a different  cache  driver  locally  than  you  do  on  your 
production  server.  It’s  easy  using  environment  based  configuration. 
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To  make  this  a cinch,  Laravel  utilizes  the  DotEnv39  PHP  library  by  Vance  Lucas.  In  a fresh  Laravel 
installation,  the  root  directory  of  your  application  will  contain  a . env.  example  file.  If  you  install 
Laravel  via  Composer,  this  file  will  automatically  be  renamed  to  . env.  Otherwise,  you  should  rename 
the  file  manually. 

All  of  the  variables  listed  in  this  file  will  be  loaded  into  the  $_ENV  PHP  super-global  when  your 
application  receives  a request.  However,  you  may  use  the  env  helper  to  retrieve  values  from  these 
variables  in  your  configuration  files.  In  fact,  if  you  review  the  Laravel  configuration  files,  you  will 
notice  several  of  the  options  already  using  this  helper: 


1 'debug'  =>  env( 'APP_DEBUG' , false), 


The  second  value  passed  to  the  env  function  is  the  “default  value”.  This  value  will  be  used  if  no 
environment  variable  exists  for  the  given  key. 

Your  . env  file  should  not  be  committed  to  your  application’s  source  control,  since  each  developer  / 
server  using  your  application  could  require  a different  environment  configuration. 

If  you  are  developing  with  a team,  you  may  wish  to  continue  including  a .env.  example  file  with 
your  application.  By  putting  place-holder  values  in  the  example  configuration  file,  other  developers 
on  your  team  can  clearly  see  which  environment  variables  are  needed  to  run  your  application. 

Determining  The  Current  Environment 

The  current  application  environment  is  determined  via  the  APP_ENV  variable  from  your  .env  file. 
You  may  access  this  value  via  the  environment  method  on  the  App  facade: 

1 Senvironment  = App : : environment ) ; 


You  may  also  pass  arguments  to  the  environment  method  to  check  if  the  environment  matches  a 
given  value.  If  necessary,  you  may  even  pass  multiple  values  to  the  environment  method.  If  the 
environment  matches  any  of  the  given  values,  the  method  will  return  true: 


39https://github.com/vlucas/phpdotenv 
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1 if  (App :: environment!  ' local ') ) { 

//  The  environment  is  local 

3 } 

4 

5 if  (App :: environment ' local ' , 'staging'))  { 

//  The  environment  is  either  local  OR  staging... 

7 } 


An  application  instance  may  also  be  accessed  via  the  app  helper  method: 


1 $environment  = app( ) - >environment( ) ; 


Configuration  Caching 

To  give  your  application  a speed  boost,  you  should  cache  all  of  your  configuration  files  into  a single 
file  using  the  config:  cache  Artisan  command.  This  will  combine  all  of  the  configuration  options 
for  your  application  into  a single  file  which  will  be  loaded  quickly  by  the  framework. 

You  should  typically  run  the  php  artisan  config: cache  command  as  part  of  your  production 
deployment  routine.  The  command  should  not  be  run  during  local  development  as  configuration 
options  will  frequently  need  to  be  changed  during  the  course  of  your  application’s  development. 

Maintenance  Mode 

When  your  application  is  in  maintenance  mode,  a custom  view  will  be  displayed  for  all  requests 
into  your  application.  This  makes  it  easy  to  "disable”  your  application  while  it  is  updating  or  when 
you  are  performing  maintenance.  A maintenance  mode  check  is  included  in  the  default  middleware 
stack  for  your  application.  If  the  application  is  in  maintenance  mode,  a MaintenanceModeException 
will  be  thrown  with  a status  code  of  503. 

To  enable  maintenance  mode,  simply  execute  the  down  Artisan  command: 

1 php  artisan  down 


You  may  also  provide  message  and  retry  options  to  the  down  command.  The  message  value  may  be 
used  to  display  or  log  a custom  message,  while  the  retry  value  will  be  set  as  the  Retry-After  HTTP 
header’s  value: 
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1 php  artisan  down  - -message^ ' Upgrading  Database'  --retry=60 


To  disable  maintenance  mode,  use  the  up  command: 


1 php  artisan  up 


Maintenance  Mode  Response  Template 

The  default  template  for  maintenance  mode  responses  is  located  in  resources/ v i ews/error  s/503  .blade. php. 
You  are  free  to  modify  this  view  as  needed  for  your  application. 

Maintenance  Mode  & Queues 

While  your  application  is  in  maintenance  mode,  no  queued  jobs  will  be  handled.  The  jobs  will 
continue  to  be  handled  as  normal  once  the  application  is  out  of  maintenance  mode. 

Alternatives  To  Maintenance  Mode 

Since  maintenance  mode  requires  your  application  to  have  several  seconds  of  downtime,  you  may 
consider  alternatives  like  Envoyer40  to  accomplish  zero-downtime  deployment  with  Laravel. 

40https://envoyer.io 
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Introduction 


Laravel  strives  to  make  the  entire  PHP  development  experience  delightful,  including  your  local 
development  environment.  Vagrant41  provides  a simple,  elegant  way  to  manage  and  provision 
Virtual  Machines. 

Laravel  Homestead  is  an  official,  pre-packaged  Vagrant  box  that  provides  you  a wonderful  devel- 
opment environment  without  requiring  you  to  install  PHP,  HHVM,  a web  server,  and  any  other 
server  software  on  your  local  machine.  No  more  worrying  about  messing  up  your  operating  system! 
Vagrant  boxes  are  completely  disposable.  If  something  goes  wrong,  you  can  destroy  and  re-create 
the  box  in  minutes! 

Homestead  runs  on  any  Windows,  Mac,  or  Linux  system,  and  includes  the  Nginx  web  server,  PHP 
7.0,  MySQL,  Postgres,  Redis,  Memcached,  Node,  and  all  of  the  other  goodies  you  need  to  develop 
amazing  Laravel  applications. 


Note:  If  you  are  using  Windows,  you  may  need  to  enable  hardware  virtualization  (VT-x). 
It  can  usually  be  enabled  via  your  BIOS. 


Included  Software 

• Ubuntu  14.04 

• Git 

. PHP  7.0 

• HHVM 

• Nginx 

• MySQL 

41http://vagr  antup.com 
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• Sqlite3 

• Postgres 

• Composer 

• Node  (With  PM2,  Bower,  Grunt,  and  Gulp) 

• Redis 

• Menrcached 

• Beanstalkd 

Installation  & Setup 

First  Steps 

Before  launching  your  Homestead  environment,  you  must  install  VirtualBox  5.x42  or  VMWare43  as 
well  as  Vagrant44.  All  of  these  software  packages  provide  easy-to-use  visual  installers  for  all  popular 
operating  systems. 

To  use  the  VMware  provider,  you  will  need  to  purchase  both  VMware  Fusion  / Workstation  and 
the  VMware  Vagrant  plug-in45.  Though  it  is  not  free,  VMware  can  provide  faster  shared  folder 
performance  out  of  the  box. 

Installing  The  Homestead  Vagrant  Box 

Once  VirtualBox  / VMware  and  Vagrant  have  been  installed,  you  should  add  the  laravel /homestead 
box  to  your  Vagrant  installation  using  the  following  command  in  your  terminal.  It  will  take  a few 
minutes  to  download  the  box,  depending  on  your  Internet  connection  speed: 


1 vagrant  box  add  laravel/homestead 


If  this  command  fails,  make  sure  your  Vagrant  installation  is  up  to  date. 

Installing  Homestead 

You  may  install  Homestead  by  simply  cloning  the  repository.  Consider  cloning  the  repository  into 
a Homestead  folder  within  your  “home”  directory,  as  the  Homestead  box  will  serve  as  the  host  to  all 
of  your  Laravel  projects: 


42https://www.virtualbox.org/wiki/Downloads 
43http :// www.  vmware  .com 
44http://www.vagrantup.com/downloads.html 
45http://www.vagrantup.com/vmware 
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1 cd  ~ 

2 

3 git  clone  https://github.com/laravel/homestead.git  Homestead 


Once  you  have  cloned  the  Homestead  repository,  run  the  bash  init.sh  command  from  the 
Homestead  directory  to  create  the  Homestead  . yaml  configuration  file.  The  Homestead  . yaml  file  will 
be  placed  in  the  ~/ . homestead  hidden  directory: 


1 bash  init.sh 


Configuring  Homestead 

Setting  Your  Provider 

The  provider  key  in  your  ~/ . homestead/Homestead . yaml  file  indicates  which  Vagrant  provider 
should  be  used:  virtualbox,  vmware_fusion,  or  vmware_workstation.  You  may  set  this  to  the 
provider  you  prefer: 

1 provider  virtualbox 


Configuring  Shared  Folders 

The  folders  property  of  the  Homestead . yaml  file  lists  all  of  the  folders  you  wish  to  share  with  your 
Homestead  environment.  As  files  within  these  folders  are  changed,  they  will  be  kept  in  sync  between 
your  local  machine  and  the  Homestead  environment.  You  may  configure  as  many  shared  folders  as 
necessary: 

1 folders: 

- map:  ~/Code 

to:  /home/vagrant/Code 


To  enable  NFS46,  just  add  a simple  flag  to  your  synced  folder  configuration: 

4 6http  ://docs . vagrantup . com/  v2/synced-  folders/nfs.html 
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1 folders: 

- map:  ~/Code 

to:  /home/vagrant/Code 
type:  "nfs" 


Configuring  Nginx  Sites 

Not  familiar  with  Nginx?  No  problem.  The  sites  property  allows  you  to  easily  map  a “domain” 
to  a folder  on  your  Homestead  environment.  A sample  site  configuration  is  included  in  the 
Homestead  .yam  1 file.  Again,  you  may  add  as  many  sites  to  your  Homestead  environment  as 
necessary.  Homestead  can  serve  as  a convenient,  virtualized  environment  for  every  Laravel  project 
you  are  working  on: 


1 sites: 

- map:  homestead . app 

to:  /home/vagrant/Code/Laravel/publ ic 


You  can  make  any  Homestead  site  use  HHVM47  by  setting  the  hhvm  option  to  true: 
1 sites: 

- map:  homestead . app 

to : /home/vagrant/Code/Laravel /publ ic 
4 hhvm:  true 


If  you  change  the  sites  property  after  provisioning  the  Homestead  box,  you  should  re-run  vagrant 
reload  - -provision  to  update  the  Nginx  configuration  on  the  virtual  machine. 

The  Hosts  File 

You  must  add  the  “domains”  for  your  Nginx  sites  to  the  hosts  file  on  your  machine.  The  hosts  file 
will  redirect  requests  for  your  Homestead  sites  into  your  Homestead  machine.  On  Mac  and  Linux, 
this  file  is  located  at /etc/hosts.  On  Windows,  it  is  located  at  C : \Windows\System32\drivers\etc\hosts. 
The  lines  you  add  to  this  file  will  look  like  the  following: 


47http://hhvm.com 
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1 192.168.10.10  homestead . app 


Make  sure  the  IP  address  listed  is  the  one  set  in  your  ~/ . homestead/Homestead  . yaml  file.  Once  you 
have  added  the  domain  to  your  hosts  file,  you  can  access  the  site  via  your  web  browser: 

1 http://homestead.app 


Launching  The  Vagrant  Box 

Once  you  have  edited  the  Homestead . yaml  to  your  liking,  run  the  vagrant  up  command  from  your 
Homestead  directory  Vagrant  will  boot  the  virtual  machine  and  automatically  configure  your  shared 
folders  and  Nginx  sites. 

To  destroy  the  machine,  you  may  use  the  vagrant  destroy  - - force  command. 

Per  Project  Installation 

Instead  of  installing  Homestead  globally  and  sharing  the  same  Homestead  box  across  all  of  your 
projects,  you  may  instead  configure  a Homestead  instance  for  each  project  you  manage.  Installing 
Homestead  per  project  may  be  beneficial  if  you  wish  to  ship  a Vagrant  file  with  your  project, 
allowing  others  working  on  the  project  to  simply  vagrant  up. 

To  install  Homestead  directly  into  your  project,  require  it  using  Composer: 

1 composer  require  laravel/homestead  --dev 


Once  Homestead  has  been  installed,  use  the  make  command  to  generate  the  Vagrantfile  and 
Homestead  . yaml  file  in  your  project  root.  The  make  command  will  automatically  configure  the  sites 
and  folders  directives  in  the  Homestead  .yaml  file. 

Mac  / Linux: 

1 php  vendor/bin/homestead  make 


Windows: 
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1 vendor \bin\homestead  make 


Next,  run  the  vagrant  up  command  in  your  terminal  and  access  your  project  at  http : //homestead  . app 
in  your  browser.  Remember,  you  will  still  need  to  add  an  /etc/hosts  file  entry  for  homestead . app 
or  the  domain  of  your  choice. 

Daily  Usage 

Accessing  Homestead  Globally 

Sometimes  you  may  want  to  vagrant  up  your  Homestead  machine  from  anywhere  on  your 
filesystem.  You  can  do  this  by  adding  a simple  Bash  alias  to  your  Bash  profile.  This  alias  will  allow 
you  to  run  any  Vagrant  command  from  anywhere  on  your  system  and  will  automatically  point  that 
command  to  your  Homestead  installation: 

1 alias  homestead= ' function  homestead()  { (cd  "/Homestead  &&  vagrant  $*);  unset  \ 

2 -f  homestead;  };  homestead' 


Make  sure  to  tweak  the  ~/Homestead  path  in  the  alias  to  the  location  of  your  actual  Homestead 
installation.  Once  the  alias  is  installed,  you  may  run  commands  like  homestead  up  or  homestead 
ssh  from  anywhere  on  your  system. 

Connecting  Via  SSH 

You  can  SSH  into  your  virtual  machine  by  issuing  the  vagrant  ssh  terminal  command  from  your 
Homestead  directory. 

But,  since  you  will  probably  need  to  SSH  into  your  Homestead  machine  frequently,  consider  adding 
the  “alias”  described  above  to  your  host  machine  to  quickly  SSH  into  the  Homestead  box. 

Connecting  To  Databases 

A homestead  database  is  configured  for  both  MySQL  and  Postgres  out  of  the  box.  For  even  more 
convenience,  Laravel’s  . env  file  configures  the  framework  to  use  this  database  out  of  the  box. 

To  connect  to  your  MySQL  or  Postgres  database  from  your  host  machine  via  Navicat  or  Sequel  Pro, 
you  should  connect  to  127.0.0.1  and  port  33060  (MySQL)  or  54320  (Postgres).  The  username  and 
password  for  both  databases  is  homestead  / secret. 
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Note:  You  should  only  use  these  non-standard  ports  when  connecting  to  the  databases  from 
your  host  machine.  You  will  use  the  default  3306  and  5432  ports  in  your  Laravel  database 
configuration  file  since  Laravel  is  running  within  the  virtual  machine. 


Adding  Additional  Sites 

Once  your  Homestead  environment  is  provisioned  and  running,  you  may  want  to  add  additional 
Nginx  sites  for  your  Laravel  applications.  You  can  run  as  many  Laravel  installations  as  you 
wish  on  a single  Homestead  environment.  To  add  an  additional  site,  simply  add  the  site  to  your 
~/  . homestead/Homestead  . yaml  file  and  then  run  the  vagrant  provision  terminal  command  from 
your  Homestead  directory 

Configuring  Cron  Schedules 

Laravel  provides  a convenient  way  to  schedule  Cron  jobs  by  scheduling  a single  schedule: run 
Artisan  command  to  be  run  every  minute.  The  schedule: run  command  will  examine  the  job 
scheduled  defined  in  your  App\Console\Kernel  class  to  determine  which  jobs  should  be  run. 

If  you  would  like  the  schedule: run  command  to  be  run  for  a Homestead  site,  you  may  set  the 
schedule  option  to  true  when  defining  the  site: 

1 sites: 

- map : homestead . app 

to:  /home/vagrant/Code/Laravel/publ ic 
4 schedule:  true 


The  Cron  job  for  the  site  will  be  defined  in  the  /etc/cron . d folder  of  the  virtual  machine. 

Ports 

By  default,  the  following  ports  are  forwarded  to  your  Homestead  environment: 

• SSH:  2222  — >■  Forwards  To  22 

• HTTP:  8000  — > Forwards  To  80 

• HTTPS:  44300  — > Forwards  To  443 

• MySQL:  33060  — > Forwards  To  3306 

• Postgres:  54320  — >■  Forwards  To  5432 
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Forwarding  Additional  Ports 

If  you  wish,  you  may  forward  additional  ports  to  the  Vagrant  box,  as  well  as  specify  their  protocol: 

1 ports : 

- send : 93000 

3 to : 9300 

4 - send : 7777 

5 to:  777 
protocol : udp 
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Introduction 

This  quickstart  guide  provides  a basic  introduction  to  the  Laravel  framework  and  includes  content 
on  database  migrations,  the  Eloquent  ORM,  routing,  validation,  views,  and  Blade  templates.  This  is 
a great  starting  point  if  you  are  brand  new  to  the  Laravel  framework  or  PHP  frameworks  in  general. 
If  you  have  already  used  Laravel  or  other  PHP  frameworks,  you  may  wish  to  consult  one  of  our 
more  advanced  quickstarts. 

To  sample  a basic  selection  of  Laravel  features,  we  will  build  a simple  task  list  we  can  use  to  track  all 
of  the  tasks  we  want  to  accomplish.  In  other  words,  the  typical  “to-do”  list  example.  The  complete, 
finished  source  code  for  this  project  is  available  on  GitHub48. 


Installation 

Installing  Laravel 

Of  course,  first  you  will  need  a fresh  installation  of  the  Laravel  framework.  You  may  use  the 
Homestead  virtual  machine  or  the  local  PHP  environment  of  your  choice  to  run  the  framework. 
Once  your  local  environment  is  ready,  you  may  install  the  Laravel  framework  using  Composer: 

1 composer  create-project  laravel/laravel  quickstart  - -prefer-dist 


48https://github.com/laravel/quickstart-basic 
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Installing  The  Quickstart  (Optional) 

You’re  free  to  just  read  along  for  the  remainder  of  this  quickstart;  however,  if  you  would  like  to 
download  the  source  code  for  this  quickstart  and  run  it  on  your  local  machine,  you  may  clone  its 
Git  repository  and  install  its  dependencies: 


1 git  clone  https://github.com/laravel/quickstart-basic  quickstart 

2 cd  quickstart 

3 composer  install 

4 php  artisan  migrate 


For  more  complete  documentation  on  building  a local  Laravel  development  environment,  check  out 
the  full  Homestead  and  installation  documentation. 

PreppingThe  Database 

Database  Migrations 

First,  let’s  use  a migration  to  define  a database  table  to  hold  all  of  our  tasks.  Laravel’s  database 
migrations  provide  an  easy  way  to  define  your  database  table  structure  and  modifications  using 
fluent,  expressive  PHP  code.  Instead  of  telling  your  team  members  to  manually  add  columns  to 
their  local  copy  of  the  database,  your  teammates  can  simply  run  the  migrations  you  push  into  source 
control. 

So,  let’s  build  a database  table  that  will  hold  all  of  our  tasks.  The  Artisan  CLI  can  be  used  to  generate 
a variety  of  classes  and  will  save  you  a lot  of  typing  as  you  build  your  Laravel  projects.  In  this  case, 
let’s  use  the  make : migration  command  to  generate  a new  database  migration  for  our  tasks  table: 


1 php  artisan  make : migration  create_tasks_table  - -create=tasks 


The  migration  will  be  placed  in  the  database/migrations  directory  of  your  project.  As  you 
may  have  noticed,  the  make: migration  command  already  added  an  auto-incrementing  ID  and 
timestamps  to  the  migration  fde.  Let’s  edit  this  file  and  add  an  additional  string  column  for  the 
name  of  our  tasks: 
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1 < ?php 

2 

3 use  1 1 luminate\Database\Schema\Bluepr int; 

4 use  1 1 luminate\Database\Migrations\Migration; 

5 

6 class  CreateTasksTable  extends  Migration 

7 { 

8 /** 

9 * Run  the  migrations . 

10  * 

11  * @return  void 

12  */ 

13  public  function  up() 

14  { 

Schema :: create( 1 tasks ' , function  (Blueprint  Stable)  { 

16  $table-> increments( ' id  1 ) ; 

17  Stable- >string( ' name  1 ) ; 

18  Stable- >timestamps( ) ; 

19  }); 

20  } 

21 

22  /** 

23  * Reverse  the  migrations . 

24  * 

25  * §return  void 

26  V 

27  public  function  down() 

28  { 

Schema : : drop( 1 tasks ' ) ; 

30  } 

31  } 


To  run  our  migration,  we  will  use  the  migrate  Artisan  command.  If  you  are  using  Homestead,  you 
should  run  this  command  from  within  your  virtual  machine,  since  your  host  machine  will  not  have 
direct  access  to  the  database: 

1 php  artisan  migrate 


This  command  will  create  all  of  our  database  tables.  If  you  inspect  the  database  tables  using  the 
database  client  of  your  choice,  you  should  see  a new  tasks  table  which  contains  the  columns  defined 
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in  our  migration.  Next,  we’re  ready  to  define  an  Eloquent  ORM  model  for  our  tasks! 

Eloquent  Models 

Eloquent  is  Laravel’s  default  ORM  (object-relational  mapper).  Eloquent  makes  it  painless  to  retrieve 
and  store  data  in  your  database  using  clearly  defined  “models”.  Usually,  each  Eloquent  model 
corresponds  directly  with  a single  database  table. 

So,  let’s  define  a Task  model  that  corresponds  to  our  tasks  database  table  we  just  created.  Again,  we 
can  use  an  Artisan  command  to  generate  this  model.  In  this  case,  we’ll  use  the  make : model  command: 


1 php  artisan  make: model  Task 


The  model  will  be  placed  in  the  app  directory  of  your  application.  By  default,  the  model  class  is 
empty.  We  do  not  have  to  explicitly  tell  the  Eloquent  model  which  table  it  corresponds  to  because  it 
will  assume  the  database  table  is  the  plural  form  of  the  model  name.  So,  in  this  case,  the  Task  model 
is  assumed  to  correspond  with  the  tasks  database  table.  Here  is  what  our  empty  model  should  look 
like: 


1 < ?php 

2 

3 namespace  App; 

4 

5 use  1 1 luminate\Database\Eloquent\Model ; 

6 

7 class  Task  extends  Model 

8 { 

9 // 

10  } 


We’ll  learn  more  about  how  to  use  Eloquent  models  as  we  add  routes  to  our  application.  Of  course, 
feel  free  to  consult  the  complete  Eloquent  documentation  for  more  information. 

Routing 

Stubbing  The  Routes 

Next,  we’re  ready  to  add  a few  routes  to  our  application.  Routes  are  used  to  point  URLs  to  controllers 
or  anonymous  functions  that  should  be  executed  when  a user  accesses  a given  page.  By  default,  all 
Laravel  routes  are  defined  in  the  app/Http/routes . php  file  that  is  included  in  every  new  project. 
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For  this  application,  we  know  we  will  need  at  least  three  routes:  a route  to  display  a list  of  all  of  our 
tasks,  a route  to  add  new  tasks,  and  a route  to  delete  existing  tasks.  We’ll  wrap  all  of  these  routes  in 
the  web  middleware  so  they  have  session  state  and  CSRF  protection.  So,  let’s  stub  all  of  these  routes 
in  the  app/Http/routes . php  file: 

1 < ?php 

2 

3 use  App\Task; 

4 use  1 1 luminate\Http\Request; 

5 

6 Route  : group( [' middleware ' =>  'web'],  function  ()  { 

7 

8 /** 

9 * Show  Task  Dashboard 

10  */ 

11  Route :: get( '/' , function  ()  { 

12  // 

13  }); 

14 

15  /** 

16  * Add  New  Task 

17  */ 

18  Route :: post( ' /task ' , function  (Request  $request)  { 

19  // 

20  }); 

21 

22  /** 

23  * Delete  Task 

24  */ 

25  Route :: delete( ' /task/{task} ' , function  (Task  $task)  { 

26  // 

27  }); 

28  }); 


Displaying  A View 

Next,  let’s  fill  out  our  / route.  From  this  route,  we  want  to  render  an  HTML  template  that  contains 
a form  to  add  new  tasks,  as  well  as  a list  of  all  current  tasks. 

In  Laravel,  all  HTML  templates  are  stored  in  the  resources/views  directory,  and  we  can  use  the 
view  helper  to  return  one  of  these  templates  from  our  route: 
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1 Route :: get( , function  ()  { 
return  view( ' tasks ') ; 

3 }); 


Passing  tasks  to  the  view  function  will  create  a View  object  instance  that  corresponds  to  the  template 
in  resources/views/tasks . blade . php.  Of  course,  we  need  to  actually  define  this  view,  so  let’s  do 
that  now! 

Building  Layouts  & Views 

This  application  only  has  a single  view  which  contains  a form  for  adding  new  tasks  as  well  as  a listing 
of  all  current  tasks.  To  help  you  visualize  the  view,  here  is  a screenshot  of  the  finished  application 
with  basic  Bootstrap  CSS  styling  applied: 


A 

Application  Image 


Defining  The  Layout 

Almost  all  web  applications  share  the  same  layout  across  pages.  For  example,  this  application  has  a 
top  navigation  bar  that  would  be  typically  present  on  every  page  (if  we  had  more  than  one).  Laravel 
makes  it  easy  to  share  these  common  features  across  every  page  using  Blade  layouts. 

As  we  discussed  earlier,  all  Laravel  views  are  stored  in  resources/views.  So,  let’s  define  a new 
layout  view  in  resources/vi ews/layouts/app . blade . php.  The  .blade . php  extension  instructs  the 
framework  to  use  the  Blade  templating  engine  to  render  the  view.  Of  course,  you  may  use  plain 
PHP  templates  with  Laravel.  However,  Blade  provides  convenient  short-cuts  for  writing  clean,  terse 
templates. 

Our  app . blade . php  view  should  look  like  the  following: 
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1 

2 

3 

4 

5 

6 

7 

8 
9 

10 

11 

12 

13 

14 

15 

16 

17 

18 

19 

20 


/ / resources/views/layouts/app . blade . php 


< ! DOCTYPE  html > 

<html  lang="en"> 

<head> 

<title>Laravel  Quickstart  - Basic</title> 

</--  CSS  And  JavaScript  --> 

</head> 


<body> 

<div  class=" container " > 
<nav  class="navbar  navbar-default"> 

<!--  Navbar  Contents  --> 


</nav> 


</div> 


@yield( 'content'  ) 

</body> 

</html> 


Note  the  §yield(  'content' ) portion  of  the  layout.  This  is  a special  Blade  directive  that  specifies 
where  all  child  pages  that  extend  the  layout  can  inject  their  own  content.  Next,  let’s  define  the  child 
view  that  will  use  this  layout  and  provide  its  primary  content. 

Defining  The  Child  View 

Next,  we  need  to  define  a view  that  contains  a form  to  create  a new  task  as  well  as  a table  that  lists 
all  existing  tasks.  Let’s  define  this  view  in  resources/views/tasks  .blade . php. 

We’ll  skip  over  some  of  the  Bootstrap  CSS  boilerplate  and  only  focus  on  the  things  that  matter. 
Remember,  you  can  download  the  full  source  for  this  application  on  GitHub49: 


49https://github.com/laravel/ quickstart- basic 
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1 //  resources/vi ews/tasks . blade . php 

2 

3 @extends( ' layouts . app ' ) 

4 

5 §section( 1 content ' ) 

6 

7 <!--  Bootstrap  Boilerplate...  --> 

8 

9 <div  class="panel -body"> 

10  <!--  Display  Validation  Errors  --> 

11  @include( ' common . errors ' ) 

12 

13  <!--  New  Task  Form  --> 

14  <form  action  url('task')  }}"  method="POST"  class=" form-horizontal " > 

15  {!!  csrf_field()  !!} 

16 

17  < ! - - Task  Name  - - > 

18  <div  class=" form-group" > 

19  <label  for="task"  class="col -sm-3  control  - label " >Task</label > 

20 

21  <div  class="col -sm-6" > 

< input  type="text"  name="name"  id  "task-name"  class=" form-control " > 

</div> 

24  </div> 

25 

26  <!--  Add  Task  Button  --> 

27  <div  class=" form-group" > 

28  <div  class="col -sm-of fset-3  col-sm-6"> 

<button  type="submit"  class="btn  btn-default" > 

30  <i  class="fa  fa-plus" > </i > Add  Task 

31  </button> 

</div> 

33  </div> 

34  </form> 

35  </div> 

36 

37  <!--  TODO:  Current  Tasks  --> 

38  @endsection 


A Few  Notes  Of  Explanation 

Before  moving  on,  let’s  talk  about  this  template  a bit.  First,  the  @extends  directive  informs  Blade 
that  we  are  using  the  layout  we  defined  in  resources/views/layouts/app . blade . php.  All  of  the 
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content  between  @section(  'content'  ) and  @endsection  will  be  injected  into  the  location  of  the 
@yield( ' content'  ) directive  within  the  app .blade . php  layout. 

The§include(  ' common  . errors  ' ) directive  will  load  the  template  located  at  resources/views/com- 
mon/errors .blade . php.  We  haven’t  defined  this  template,  but  we  will  soon! 

Now  we  have  defined  a basic  layout  and  view  for  our  application.  Remember,  we  are  returning  this 
view  from  our  / route  like  so: 


1 Route :: get( '/' , function  ()  { 
return  view( 1 tasks ') ; 

3 }); 


Next,  we’re  ready  to  add  code  to  our  POST  /task  route  to  handle  the  incoming  form  input  and  add 
a new  task  to  the  database. 

Adding  Tasks 

Validation 

Now  that  we  have  a form  in  our  view,  we  need  to  add  code  to  our  POST  /task  route  to  validate  the 
incoming  form  input  and  create  a new  task.  First,  let’s  validate  the  input. 

For  this  form,  we  will  make  the  name  field  required  and  state  that  it  must  contain  less  than  255 
characters.  If  the  validation  fails,  we  will  redirect  the  user  back  to  the  / URL,  as  well  as  flash  the  old 
input  and  errors  into  the  session.  Flashing  the  input  into  the  session  will  allow  us  to  maintain  the 
user’s  input  even  when  there  are  validation  errors: 


1 Route :: post( ' /task ' , function  (Request  $request)  { 

Svalidator  = Validator: :make($request->all( ),  [ 
'name'  =>  ' required  I max : 255 ' , 

4 ]); 

5 

6 if  ($val idator- > fai ls( ) ) { 

7 return  redirect( ' / ' ) 

8 - >withlnput( ) 

9 - >withErrors($val idator ) ; 

10  } 

11 

12  //  Create  The  Task. . . 
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13  }); 


The  $errors  Variable 

Let’s  take  a break  for  a moment  to  talk  about  the  ->withErrors($val idator)  portion  of  this 
example.  The  ->withErrors($val  idator)  call  will  flash  the  errors  from  the  given  validator  instance 
into  the  session  so  that  they  can  be  accessed  via  the  $errors  variable  in  our  view. 

Remember  that  we  used  the  @include( ' common . errors ' ) directive  within  our  view  to  render  the 
form’s  validation  errors.  The  common . errors  will  allow  us  to  easily  show  validation  errors  in  the 
same  format  across  all  of  our  pages.  Let’s  define  the  contents  of  this  view  now: 

1 //  resources/vi ews/common/errors . bl ade . php 

2 

3 §if  (count($errors)  > 0) 

4 <!--  Form  Error  List  --> 

5 <div  class="alert  alert-danger" > 

6 < strong > Whoops ! Something  went  wrong ! </strong> 

7 

8 <br>  <br > 

9 

10  <ul> 

11  @foreach  ($errors->all( ) as  $error) 

12  < 1 i > { { $error  }}</li> 

13  ©endforeach 

14  </ul> 

15  </div> 

16  @endif 


Note:  The  $errors  variable  is  available  in  every  Laravel  view.  It  will  simply  be  an  empty 
instance  of  ViewErrorBag  if  no  validation  errors  are  present. 


Creating  The  Task 

Now  that  input  validation  is  handled,  let’s  actually  create  a new  task  by  continuing  to  fill  out  our 
route.  Once  the  new  task  has  been  created,  we  will  redirect  the  user  back  to  the  / URL.  To  create  the 
task,  we  may  use  the  save  method  after  creating  and  setting  properties  on  a new  Eloquent  model: 
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1 Route :: post( ' /task ' , function  (Request  $request)  { 

$validator  = Val idator : : make($request- >al 1 ( ) , [ 
'name'  =>  ' required | max : 255 ' , 

4 ]); 

5 

6 if  ($ val idator- > fai ls( ) ) { 

7 return  redirect( ' / ' ) 

8 - >withlnput( ) 

9 - >withErrors($val idator ) ; 


10 

} 

11 

12 

$task  = new  Task; 

13 

$task->name  = $request->name 

14 

$task- >save( ) ; 

15 

16 

return  redirect( ' / ' ) ; 

17  }); 

Great!  We  can  now  successfully  create  tasks.  Next,  let’s  continue  adding  to  our  view  by  building  a 
list  of  all  existing  tasks. 

Displaying  Existing  Tasks 


First,  we  need  to  edit  our  / route  to  pass  all  of  the  existing  tasks  to  the  view.  The  view  function 
accepts  a second  argument  which  is  an  array  of  data  that  will  be  made  available  to  the  view,  where 
each  key  in  the  array  will  become  a variable  within  the  view: 


1 

Route : 

:get('/',  function  ()  { 

2 

$tasks  = Task  orderBy( ' created_at 1 , 

'asc' ) - >get( ) ; 

3 

4 

return  view( ' tasks ' , [ 

5 

'tasks'  =>  $tasks 

6 

7); 

7 

1); 

Once  the  data  is  passed,  we  can  spin  through  the  tasks  in  our  tasks . blade . php  view  and  display 
them  in  a table.  The  @ for  each  Blade  construct  allows  us  to  write  concise  loops  that  compile  down 
into  blazing  fast  plain  PHP  code: 
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1 

2 

3 

4 

5 

6 

7 

8 
9 

10 

11 

12 

13 

14 

15 

16 

17 

18 

19 

20 
21 
22 

23 

24 

25 

26 

27 

28 

29 

30 

31 

32 

33 

34 

35 

36 

37 

38 

39 

40 

41 


@extends( ' layouts . app ' ) 

@section( 'content' ) 

<!--  Create  Task  Form...  --> 

<!--  Current  Tasks  --> 

@if  (count($tasks)  > 0) 

<div  class="panel  panel -default" > 
<div  class="panel -heading") 
Current  Tasks 
</div> 


<div  class="panel -body " > 

<table  class="table  table-striped  task-table") 

<!--  Table  Headings  --> 

<thead> 

<th>Task</th> 

<th>&nbsp ; </th> 

</thead> 

< ! - - Table  Body  - - > 

<tbody> 

@foreach  ($tasks  as  $task) 

<tr> 

< ! - - Task  Name  - - > 

<td  class="table-text" > 

<div>{{  $task->name  }}</div> 

</td> 

<td> 

<!--  TODO:  Delete  Button  --> 

</td> 

</tr> 

§endforeach 

</tbody) 

</table> 

</div> 

</div> 

@endi f 
@endsection 
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Our  task  application  is  almost  complete.  But,  we  have  no  way  to  delete  our  existing  tasks  when 
they’re  done.  Let’s  add  that  next! 


Deleting  Tasks 

Adding  The  Delete  Button 


We  left  a “TODO”  note  in  our  code  where  our  delete  button  is  supposed  to  be.  So,  let’s  add  a delete 
button  to  each  row  of  our  task  listing  within  the  tasks . blade . php  view.  We’ll  create  a small  single- 
button form  for  each  task  in  the  list.  When  the  button  is  clicked,  a DELETE  /task  request  will  be  sent 
to  the  application: 

1 <tr> 

2 < ! - - Task  Name  --> 

<td  c 1 ass= " tab 1 e - text " > 

4 <div>/Y  $task->name  jj</div> 

5 </td> 

6 

7 <!--  Delete  Button  --> 

8 <td> 

9 <form  action^"//  url( 'task/' .$task->id)  }}"  method="POST"> 

10  {!!  csrf_field()  !!} 

11  {!!  method_field( 'DELETE' ) !!} 

12 

13  <button>Delete  Task</button> 

14  </form> 

15  </td> 

16  </tr> 


A Note  On  Method  Spoofing 

Note  that  the  delete  button’s  form  method  is  listed  as  POST,  even  though  we  are  responding  to  the 
request  using  a Route : : delete  route.  HTML  forms  only  allow  the  GET  and  POST  HTTP  verbs,  so  we 
need  a way  to  spoof  a DELETE  request  from  the  form. 

We  can  spoof  a DELETE  request  by  outputting  the  results  of  the  method_f  ield(  ' DELETE ' ) function 
within  our  form.  This  function  generates  a hidden  form  input  that  Laravel  recognizes  and  will  use 
to  override  the  actual  HTTP  request  method.  The  generated  field  will  look  like  the  following: 
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1 < input  type=" hidden"  name="_method"  value="DELETE" > 


Deleting  The  Task 

Finally,  let’s  add  logic  to  our  route  to  actually  delete  the  given  task.  We  can  use  implicit  model 
binding  to  automatically  retrieve  the  Task  model  that  corresponds  to  the  {task}  route  parameter. 

In  our  route  callback,  we  will  use  the  delete  method  to  delete  the  record.  Once  the  record  is  deleted, 
we  will  redirect  the  user  back  to  the  / URL: 

1 Route :: delete( ' /task/{task} ' , function  (Task  $task)  { 

$task- >delete( ) ; 

3 

4 return  redirect( ' / ' ) ; 

5 }); 
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Introduction 

This  quickstart  guide  provides  an  intermediate  introduction  to  the  Laravel  framework  and  includes 
content  on  database  migrations,  the  Eloquent  ORM,  routing,  authentication,  authorization,  depen- 
dency injection,  validation,  views,  and  Blade  templates.  This  is  a great  starting  point  if  you  are 
familiar  with  the  basics  of  the  Laravel  framework  or  PHP  frameworks  in  general. 

To  sample  a basic  selection  of  Laravel  features,  we  will  build  a task  list  we  can  use  to  track  all  of 
the  tasks  we  want  to  accomplish.  In  other  words,  the  typical  “to-do”  list  example.  In  contrast  to 
the  “basic”  quickstart,  this  tutorial  will  allow  users  to  create  accounts  and  authenticate  with  the 
application.  The  complete,  finished  source  code  for  this  project  is  available  on  GitHub50. 


Installation 

Installing  Laravel 

Of  course,  first  you  will  need  a fresh  installation  of  the  Laravel  framework.  You  may  use  the 
Homestead  virtual  machine  or  the  local  PHP  environment  of  your  choice  to  run  the  framework. 
Once  your  local  environment  is  ready,  you  may  install  the  Laravel  framework  using  Composer: 


50https://github.com/laravel/ quickstart- intermediate 
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1  composer  create-project  laravel/laravel  quickstart  - -prefer-dist 


Installing  The  Quickstart  (Optional) 

You’re  free  to  just  read  along  for  the  remainder  of  this  quickstart;  however,  if  you  would  like  to 
download  the  source  code  for  this  quickstart  and  run  it  on  your  local  machine,  you  may  clone  its 
Git  repository  and  install  its  dependencies: 


1 git  clone  https://github.com/laravel/quickstart-intermediate  quickstart 

2 cd  quickstart 

3 composer  install 

4 php  artisan  migrate 


For  more  complete  documentation  on  building  a local  Laravel  development  environment,  check  out 
the  full  Homestead  and  installation  documentation. 

PreppingThe  Database 

Database  Migrations 

First,  let’s  use  a migration  to  define  a database  table  to  hold  all  of  our  tasks.  Laravel’s  database 
migrations  provide  an  easy  way  to  define  your  database  table  structure  and  modifications  using 
fluent,  expressive  PHP  code.  Instead  of  telling  your  team  members  to  manually  add  columns  to 
their  local  copy  of  the  database,  your  teammates  can  simply  run  the  migrations  you  push  into  source 
control. 

The  users  Table 

Since  we  are  going  to  allow  users  to  create  their  accounts  within  the  application,  we  will  need  a 
table  to  store  all  of  our  users.  Thankfully,  Laravel  already  ships  with  a migration  to  create  a basic 
users  table,  so  we  do  not  need  to  manually  generate  one.  The  default  migration  for  the  users  table 
is  located  in  the  database/migrations  directory. 

The  tasks  Table 

Next,  let’s  build  a database  table  that  will  hold  all  of  our  tasks.  The  Artisan  CLI  can  be  used  to 
generate  a variety  of  classes  and  will  save  you  a lot  of  typing  as  you  build  your  Laravel  projects. 
In  this  case,  let’s  use  the  make: migration  command  to  generate  a new  database  migration  for  our 
tasks  table: 
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1 php  artisan  make : migration  create_tasks_table  - -create=tasks 


The  migration  will  be  placed  in  the  database/migrations  directory  of  your  project.  As  you 
may  have  noticed,  the  make: migration  command  already  added  an  auto-incrementing  ID  and 
timestamps  to  the  migration  file.  Let’s  edit  this  file  and  add  an  additional  string  column  for  the 
name  of  our  tasks,  as  well  as  a user_id  column  which  will  link  our  tasks  and  users  tables: 


1 < ?php 

2 

3 use  1 1 luminate\Database\Schema\Bluepr int; 

4 use  1 1 luminate\Database\Migrations\Migration; 

5 

6 class  CreateTasksTable  extends  Migration 

7 { 

8 /** 

9 * Run  the  migrations . 

10  * 

11  * @return  void 

12  */ 

13  public  function  up() 

14  { 

15  Schema :: create( 1 tasks ' , function  (Blueprint  Stable)  { 

16  $table->increments( ' id  1 ); 

17  $table-> integer ( ' user_id ' ) - > index ( ) ; 

18  $table->string( ' name  1 ) ; 

19  $table->timestamps( ) ; 

20  }); 

21  } 

22 

23  /** 

24  * Reverse  the  migrations . 

25  * 

26  * §return  void 

27  */ 

28  public  function  down() 

29  { 

Schema : : drop( 1 tasks ' ) ; 

31  } 

32  } 
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To  run  our  migrations,  we  will  use  the  migrate  Artisan  command.  If  you  are  using  Homestead,  you 
should  run  this  command  from  within  your  virtual  machine,  since  your  host  machine  will  not  have 
direct  access  to  the  database: 


1 php  artisan  migrate 


This  command  will  create  all  of  our  database  tables.  If  you  inspect  the  database  tables  using  the 
database  client  of  your  choice,  you  should  see  new  tasks  and  users  tables  which  contains  the 
columns  defined  in  our  migration.  Next,  we’re  ready  to  define  our  Eloquent  ORM  models! 

Eloquent  Models 

Eloquent  is  Laravel’s  default  ORM  (object-relational  mapper).  Eloquent  makes  it  painless  to  retrieve 
and  store  data  in  your  database  using  clearly  defined  “models”.  Usually,  each  Eloquent  model 
corresponds  directly  with  a single  database  table. 

The  User  Model 

First,  we  need  a model  that  corresponds  to  our  users  database  table.  However,  if  you  look  in  the  app 
directory  of  your  project,  you  will  see  that  Laravel  already  ships  with  a User  model,  so  we  do  not 
need  to  generate  one  manually. 

The  Task  Model 

So,  let’s  define  a Task  model  that  corresponds  to  our  tasks  database  table  we  just  created.  Again,  we 
can  use  an  Artisan  command  to  generate  this  model.  In  this  case,  we’ll  use  the  make : model  command: 


1 php  artisan  make: model  Task 


The  model  will  be  placed  in  the  app  directory  of  your  application.  By  default,  the  model  class  is 
empty.  We  do  not  have  to  explicitly  tell  the  Eloquent  model  which  table  it  corresponds  to  because  it 
will  assume  the  database  table  is  the  plural  form  of  the  model  name.  So,  in  this  case,  the  Task  model 
is  assumed  to  correspond  with  the  tasks  database  table. 

Let’s  add  a few  things  to  this  model.  First,  we  will  state  that  the  name  attribute  on  the  model  should 
be  “mass-assignable”.  This  will  allow  us  to  fill  the  name  attribute  when  using  Eloquent’s  create 
method: 
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1 < ?php 

2 

3 namespace  App; 

4 

5 use  1 1 luminate\Database\Eloquent\Model ; 

6 

7 class  Task  extends  Model 

8 { 

g /** 

10  * The  attributes  that  are  mass  assignable. 

11  * 

12  * §var  array 

13  */ 

14  protected  $fi liable  = ['name']; 

15  } 


We’ll  learn  more  about  how  to  use  Eloquent  models  as  we  add  routes  to  our  application.  Of  course, 
feel  free  to  consult  the  complete  Eloquent  documentation  for  more  information. 

Eloquent  Relationships 


Now  that  our  models  are  defined,  we  need  to  link  them.  For  example,  our  User  can  have  many  Task 
instances,  while  a Task  is  assigned  to  a single  User.  Defining  a relationship  will  allow  us  to  fluently 
walk  through  our  relations  like  so: 


1 

$user  = 

App\User : : f ind(l ) ; 

2 

3 

foreach 

($user- >tasks  as  $task)  { 

4 

echo  $task->name; 

5 

} 

The  tasks  Relationship 

First,  let’s  define  the  tasks  relationship  on  our  User  model.  Eloquent  relationships  are  defined  as 
methods  on  models.  Eloquent  supports  several  different  types  of  relationships,  so  be  sure  to  consult 
the  full  Eloquent  documentation  for  more  information.  In  this  case,  we  will  define  a tasks  function 
on  the  User  model  which  calls  the  hasMany  method  provided  by  Eloquent: 


Intermediate  Task  List 


90 


1 < ?php 

2 

3 namespace  App; 

4 

5 use  1 1 luminate\Foundation\Auth\User  as  Authenticatable; 

6 

7 class  User  extends  Authenticatable 

8 { 

9 //  Other  Eloquent  Properties . . . 

10 

11  /** 

12  * Get  all  of  the  tasks  for  the  user. 

13  */ 

14  public  function  tasks() 

15  { 

16  return  $this- >hasMany (Task :: class) ; 

17  } 

18  } 


The  user  Relationship 

Next,  let’s  define  the  user  relationship  on  the  Task  model.  Again,  we  will  define  the  relationship 
as  a method  on  the  model.  In  this  case,  we  will  use  the  belongsTo  method  provided  by  Eloquent  to 
define  the  relationship: 


1 < ?php 

2 

3 namespace  App; 

4 

5 use  App\User; 

6 use  1 1 luminate\Database\Eloquent\Model ; 

7 

8 class  Task  extends  Model 

9 { 

10  /** 

11  * The  attributes  that  are  mass  assignable . 

12  * 

13  * §var  array 

14  V 

15  protected  $fi liable  = ['name']; 

16 


Intermediate  Task  List 


91 


17 

/** 

18 

* Get 

the 

user 

that  owns  the  task. 

19 

V 

20 

public 

function 

user( ) 

21 

{ 

22 

return 

$this 

->belongsTo(User : :c 

23 

} 

24 

} 

Wonderful!  Now  that  our  relationships  are  defined,  we  can  start  building  our  controllers! 

Routing 

In  the  basic  version  of  our  task  list  application,  we  defined  all  of  our  logic  using  Closures  within  our 
routes . php  file.  For  the  majority  of  this  application,  we  will  use  controllers  to  organize  our  routes. 
Controllers  will  allow  us  to  break  out  HTTP  request  handling  logic  across  multiple  files  for  better 
organization. 

Displaying  A View 

We  will  have  a single  route  that  uses  a Closure:  our  / route,  which  will  simply  be  a landing  page 
for  application  guests.  So,  let’s  fill  out  our  / route.  From  this  route,  we  want  to  render  an  HTML 
template  that  contains  the  “welcome”  page: 

In  Laravel,  all  HTML  templates  are  stored  in  the  resources/views  directory,  and  we  can  use  the 
view  helper  to  return  one  of  these  templates  from  our  route: 

1 Route :: get( '/' , function  ()  { 

return  view( 1 welcome  1 ) ; 

3 }); 


Of  course,  we  need  to  actually  define  this  view.  We’ll  do  that  in  a bit! 


Authentication 

Remember,  we  also  need  to  let  users  create  accounts  and  login  to  our  application.  Typically,  it  can 
be  a tedious  task  to  build  an  entire  authentication  layer  into  a web  application.  However,  since  it  is 
such  a common  need,  Laravel  attempts  to  make  this  procedure  totally  painless. 
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First,  notice  that  there  is  already  a app/Http/Control  lers/Auth/AuthControl  ler  included  in  your 
Laravel  application.  This  controller  uses  a special  AuthenticatesAndRegistersUsers  trait  which 
contains  all  of  the  necessary  logic  to  create  and  authenticate  users. 

Authentication  Routes  & Views 

So,  what’s  left  for  us  to  do?  Well,  we  still  need  to  create  the  registration  and  login  templates  as 
well  as  define  the  routes  to  point  to  the  authentication  controller.  We  can  do  all  of  this  using  the 
make:auth  Artisan  command: 

1 php  artisan  make:auth  --views 


Note:  If  you  would  like  to  view  complete  examples  for  these  views,  remember  that  the 
entire  application’s  source  code  is  available  on  GitHub51. 


Now,  all  we  have  to  do  is  add  the  authentication  routes  to  our  routes  file.  We  can  do  this  using  the 
auth  method  on  the  Route  facade,  which  will  register  all  of  the  routes  we  need  for  registration,  login, 
and  password  reset: 

1 //  Authentication  Routes... 

2 Route : : auth( ) ; 


The  Task  Controller 

Since  we  know  we’re  going  to  need  to  retrieve  and  store  tasks,  let’s  create  a TaskControl  ler  using 
the  Artisan  CLI,  which  will  place  the  new  controller  in  the  app/Http/Control  lers  directory: 

1 php  artisan  make : control ler  TaskControl ler 


Now  that  the  controller  has  been  generated,  let’s  go  ahead  and  stub  out  some  routes  in  our 
app/Http/routes . php  file  to  point  to  the  controller: 


51https://github.com/laravel/quickstart- intermediate 


Intermediate  Task  List 


93 


1 Route :: get( ' /tasks ' , ' TaskControl ler§index ') ; 

2 Route :: post( ' /task  1 11 , ' TaskControl ler@store ') ; 

3 Route :: delete( ' /task/{task} ' , ' TaskControl ler§destroy ') ; 


Authenticating  All  Task  Routes 

For  this  application,  we  want  all  of  our  task  routes  to  require  an  authenticated  user.  In  other  words, 
the  user  must  be  “logged  into”  the  application  in  order  to  create  a task.  So,  we  need  to  restrict  access 
to  our  task  routes  to  only  authenticated  users.  Laravel  makes  this  a cinch  using  middleware. 

To  require  an  authenticated  users  for  all  actions  on  the  controller,  we  can  add  a call  to  the 
middleware  method  from  the  controller’s  constructor.  All  available  route  middleware  are  defined  in 
the  app/Http/Kernel . php  file.  In  this  case,  we  want  to  assign  the  auth  middleware  to  all  actions  on 
the  controller: 


1 < ?php 

2 

3 namespace  App\Http\Control lers; 

4 

5 use  App\Http\Requests; 

6 use  1 1 luminate\Http\Request; 

7 use  App\Http\Controllers\Controller; 

8 

9  class  TaskControl ler  extends  Controller 

10  { 

11  /** 

12  * Create  a new  controller  instance. 

13  * 

14  * §return  void 

15  V 

16  public  function  .construct!) 

17  { 

18  $this- > middleware! ' auth ' ) ; 

19  } 

20  } 
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Building  Layouts  & Views 

The  primary  part  of  this  application  only  has  a single  view  which  contains  a form  for  adding  new 
tasks  as  well  as  a listing  of  all  current  tasks.  To  help  you  visualize  the  view,  here  is  a screenshot  of 
the  finished  application  with  basic  Bootstrap  CSS  styling  applied: 

A 

Application  Image 


Defining  The  Layout 

Almost  all  web  applications  share  the  same  layout  across  pages.  For  example,  this  application  has  a 
top  navigation  bar  that  would  be  typically  present  on  every  page  (if  we  had  more  than  one).  Laravel 
makes  it  easy  to  share  these  common  features  across  every  page  using  Blade  layouts. 

As  we  discussed  earlier,  all  Laravel  views  are  stored  in  resources/views.  So,  let’s  define  a new 
layout  view  in  resources/vi ews/layouts/app . blade . php.  The  .blade . php  extension  instructs  the 
framework  to  use  the  Blade  templating  engine  to  render  the  view.  Of  course,  you  may  use  plain 
PHP  templates  with  Laravel.  However,  Blade  provides  convenient  short-cuts  for  writing  cleaner, 
terse  templates. 

Our  app . blade . php  view  should  look  like  the  following: 


1 //  resources/views/layouts/app . blade . php 

2 

3 < / DOCTYPE  html> 

4 <html  lang="en"> 

5 <head> 

<title>Laravel  Quickstart  - Intermediate</title> 

7 

8 <!--  CSS  And  JavaScript  --> 

9 </head> 

10 

11  <body> 

12  <div  class=" container " > 

13  <nav  class="navbar  navbar-default"> 

14  <!--  Navbar  Contents  --> 

15  </nav> 

16  </div> 

17 

18  @yield( ' content ' ) 

19 


</body> 
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20  </html> 


Note  the  @yield(  'content' ) portion  of  the  layout.  This  is  a special  Blade  directive  that  specifies 
where  all  child  pages  that  extend  the  layout  can  inject  their  own  content.  Next,  let’s  define  the  child 
view  that  will  use  this  layout  and  provide  its  primary  content. 

Defining  The  Child  View 

Great,  our  application  layout  is  finished.  Next,  we  need  to  define  a view  that  contains  a form 
to  create  a new  task  as  well  as  a table  that  lists  all  existing  tasks.  Let’s  define  this  view  in 
resources/views/tasks/index,  blade,  php,  which  will  correspond  to  the  index  method  in  our 
TaskControl ler. 

We’ll  skip  over  some  of  the  Bootstrap  CSS  boilerplate  and  only  focus  on  the  things  that  matter. 
Remember,  you  can  download  the  full  source  for  this  application  on  GitHub52: 


1 //  resources/views/tasks/ index . blade . php 

2 

3 @extends( ' layouts . app ' ) 

4 

5 @section( ' content ' ) 

6 

<!--  Bootstrap  Boilerplate...  --> 

8 

9 <div  class="panel -body"> 

10  <!--  Display  Validation  Errors  --> 

11  @include( ' common . errors ' ) 

12 

13  <!--  New  Task  Form  --> 

14  <form  action  "{{  url('task')  }}"  method="POST"  class=" form-horizontal " > 

15  {!!  csr f_f ield( ) !!} 

16 

17  < ! - - Task  Name  - - > 

18  <div  class=" form-group" > 

19  clabel  for="task-name"  class="col -sm-3  control-label">Task</label> 

20 

21  <div  class="col -sm-6" > 

< input  type="text"  name="name"  id - "task-name"  class=" form-control " > 

</div> 

24  </div> 


52https://gi  thub.com/laravel/quickstart- intermediate 
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25 

26  <!--  Add  Task  Button  --> 

27  <div  class=" form-group" > 

<div  class="col -sm-of fset-3  col-sm-6"> 

<button  type="submit"  class="btn  btn-default"> 

30  <i  class="fa  fa-plus" > </i > Add  Task 

31  </button> 

32  </div> 

33  </div> 

34  </form> 

35  </div> 

36 

37  <!--  TODO:  Current  Tasks  --> 

38  §endsection 


A Few  Notes  Of  Explanation 

Before  moving  on,  let’s  talk  about  this  template  a bit.  First,  the  @extends  directive  informs  Blade 
that  we  are  using  the  layout  we  defined  at  resources/views/layouts/app . blade,  php.  All  of  the 
content  between  @section(  'content'  ) and  @endsection  will  be  injected  into  the  location  of  the 
@yield( ' content'  ) directive  within  the  app .blade . php  layout. 

The@include(  ' common  . errors ' ) directive  will  load  the  template  located  at  resources/views/com- 
mon/errors .blade . php.  We  haven’t  defined  this  template,  but  we  will  soon! 

Now  we  have  defined  a basic  layout  and  view  for  our  application.  Let’s  go  ahead  and  return  this 
view  from  the  index  method  of  our  TaskController: 


1 /** 

2 * Display  a list  of  all  of  the  user's  task. 

3 * 

4 * §param  Request  $request 

5 * &return  Response 

6 V 

7 public  function  index(Request  Srequest) 

8 { 

return  view( ' tasks . index ') ; 

10  } 


Next,  we’re  ready  to  add  code  to  our  POST  /task  route’s  controller  method  to  handle  the  incoming 
form  input  and  add  a new  task  to  the  database. 
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Adding  Tasks 

Validation 

Now  that  we  have  a form  in  our  view,  we  need  to  add  code  to  our  TaskController@store  method 
to  validate  the  incoming  form  input  and  create  a new  task.  First,  let’s  validate  the  input. 

For  this  form,  we  will  make  the  name  field  required  and  state  that  it  must  contain  less  than  255 
characters.  If  the  validation  fails,  we  want  to  redirect  the  user  back  to  the  /tasks  URL,  as  well  as 
flash  the  old  input  and  errors  into  the  session: 

1 /** 

2 * Create  a new  task. 

3 * 

4 * §param  Request  $ request 

5 * §return  Response 

6 V 

7 public  function  store(Request  $request) 

8 { 

$this->validate($request,  [ 

10  'name'  =>  ' required  I max : 255 ' , 

11  ]); 

12 

13  //  Create  The  Task. . . 

14  } 


If  you  followed  along  with  the  basic  quickstart,  you’ll  notice  this  validation  code  looks  quite  a bit 
different!  Since  we  are  in  a controller,  we  can  leverage  the  convenience  of  the  ValidatesRequests 
trait  that  is  included  in  the  base  Laravel  controller.  This  trait  exposes  a simple  validate  method 
which  accepts  a request  and  an  array  of  validation  rules. 

We  don’t  even  have  to  manually  determine  if  the  validation  failed  or  do  manual  redirection.  If  the 
validation  fails  for  the  given  rules,  the  user  will  automatically  be  redirected  back  to  where  they  came 
from  and  the  errors  will  automatically  be  flashed  to  the  session.  Nice! 

The  $errors  Variable 

Remember  that  we  used  the  @include( ' common . errors ' ) directive  within  our  view  to  render  the 
form’s  validation  errors.  The  common . errors  will  allow  us  to  easily  show  validation  errors  in  the 
same  format  across  all  of  our  pages.  Let’s  define  the  contents  of  this  view  now: 
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1 //  resources/views/common/errors . blade . php 

2 

3 @if  (count($errors)  > 0) 

4 <!--  Form  Error  List  --> 

5 <div  class="alert  alert-danger " > 

< strong > Whoops ! Something  went  wrong ! </strong> 

7 

8 <br>  <br> 

9 

10  <ul> 

@foreach  ($errors- >al 1 ( ) as  $error) 

12  <li>{{  $error  }}</li> 

13  @endforeach 

14  </ul> 

15  </div> 

16  @endif 


Note:  The  $errors  variable  is  available  in  every  Laravel  view.  It  will  simply  be  an  empty 
instance  of  ViewErrorBag  if  no  validation  errors  are  present. 


Creating  The  Task 

Now  that  input  validation  is  handled,  let’s  actually  create  a new  task  by  continuing  to  fill  out  our 
route.  Once  the  new  task  has  been  created,  we  will  redirect  the  user  back  to  the  /tasks  URL.  To 
create  the  task,  we  are  going  to  leverage  the  power  of  Eloquent’s  relationships. 

Most  of  Laravel’s  relationships  expose  a create  method,  which  accepts  an  array  of  attributes  and 
will  automatically  set  the  foreign  key  value  on  the  related  model  before  storing  it  in  the  database. 
In  this  case,  the  create  method  will  automatically  set  the  user_id  property  of  the  given  task  to  the 
ID  of  the  currently  authenticated  user,  which  we  are  accessing  using  $request->user( ): 
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1  /** 

2 * Create  a new  task. 

3 * 

4 * §param  Request  $ request 

5 * §return  Response 

6 V 

7 public  function  store(Request  $request) 

8 { 

$this->validate($request,  [ 

10  'name'  =>  ' required | max : 255 ' , 

11  ]); 

12 

$request->user( )->tasks( )->create( [ 
'name'  =>  $request->name, 

15  ]); 

16 

return  redirect( ' /tasks ') ; 

18  } 


Great!  We  can  now  successfully  create  tasks.  Next,  let’s  continue  adding  to  our  view  by  building  a 
list  of  all  existing  tasks. 

Displaying  Existing  Tasks 

First,  we  need  to  edit  our  TaskControl  ler@index  method  to  pass  all  of  the  existing  tasks  to  the  view. 
The  view  function  accepts  a second  argument  which  is  an  array  of  data  that  will  be  made  available 
to  the  view,  where  each  key  in  the  array  will  become  a variable  within  the  view.  For  example,  we 
could  do  this: 

1 /** 

2 * Display  a list  of  all  of  the  user's  task. 

3 * 

4 * §param  Request  $ request 

5 * §return  Response 

6 V 

7 public  function  index( Request  Srequest) 

8 { 

$tasks  = Task:  where( ' user_id ' , Srequest- >user( )-> id) - >get( ) ; 

10 
11 
12 


return  view( ' tasks . index ' , [ 
'tasks'  =>  $tasks, 
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13  J); 

14  } 


However,  let’s  explore  some  of  the  dependency  injection  capabilities  of  Laravel  to  inject  a TaskRepos- 
itory  into  our  TaskControl  ler,  which  we  will  use  for  all  of  our  data  access. 

Dependency  Injection 

Laravel’s  service  container  is  one  of  the  most  powerful  features  of  the  entire  framework.  After 
reading  this  quickstart,  be  sure  to  read  over  all  of  the  container’s  documentation. 

Creating  The  Repository 

As  we  mentioned  earlier,  we  want  to  define  a TaskRepository  that  holds  all  of  our  data  access  logic 
for  the  Task  model.  This  will  be  especially  useful  if  the  application  grows  and  you  need  to  share 
some  Eloquent  queries  across  the  application. 

So,  let’s  create  an  app/Repositories  directory  and  add  a TaskRepository  class.  Remember,  all 
Laravel  app  folders  are  auto-loaded  using  the  PSR-4  auto-loading  standard,  so  you  are  free  to  create 
as  many  extra  directories  as  needed: 


1 < ?php 

2 

3 namespace  App\Repositories; 

4 

5 use  App\User; 

6 use  App\Task; 

7 

8 class  TaskRepository 

9 { 

10  /** 

11  * Get  all  of  the  tasks  for  a given  user. 

12  * 

13  * §param  User  $user 

14  * §return  Collection 

15  V 

16  public  function  forUser(User  $user) 

17  { 

return  Task : : where( ' user_id ' , $user->id) 

19  - >orderBy( ' created_at ' , ’asc') 

20  ->get(); 

21 


} 
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22  } 


Injecting  The  Repository 

Once  our  repository  is  defined,  we  can  simply  “type-hint”  it  in  the  constructor  of  our  TaskCon- 
troller  and  utilize  it  within  our  index  route.  Since  Laravel  uses  the  container  to  resolve  all 
controllers,  our  dependencies  will  automatically  be  injected  into  the  controller  instance: 


1 < ?php 

2 

3 namespace  App\Http\Control lers; 

4 

5 use  App\Task; 

6 use  App\Http\Requests; 

7 use  1 1 luminate\Http\Request; 

8 use  App\Http\Controllers\Controller; 

9 use  App\Repositor ies\TaskRepository ; 

10 

11  class  TaskController  extends  Controller 

12  { 

13  /** 

14 *  * The  task  repository  instance. 

15  * 

16  * §var  TaskRepository 

17  */ 

18  protected  $tasks; 

19 

20  /** 

21  * Create  a new  controller  instance. 

22  * 

* §param  TaskReposi tory  $tasks 

24  * §return  void 

25  */ 

26  public  function  construct(TaskRepository  $tasks) 

27  { 

28  $this- >middleware( ' auth ' ) ; 

29 

30 

31  } 

32 

33  /** 


$this->tasks  = $tasks; 
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34  * Display  a list  of  all  of  the  user's  task. 

35  * 

36  * §param  Request  Srequest 

37  * §return  Response 

38  V 

39  public  function  index(Request  Srequest) 

40  { 

41  return  view( ' tasks . index ' , [ 

42  'tasks'  =>  Sthis- >tasks- > forUser( Srequest- >user( ) ) , 

43  ]); 

44  } 

45  } 


Displaying  The  Tasks 

Once  the  data  is  passed,  we  can  spin  through  the  tasks  in  our  tasks/index. blade. php  view  and 
display  them  in  a table.  The  @foreach  Blade  construct  allows  us  to  write  concise  loops  that  compile 
down  into  blazing  fast  plain  PHP  code: 


1 @extends( ' layouts . app ' ) 

2 

3 §section( ' content ' ) 

4 <!--  Create  Task  Form...  --> 

5 

6 <!--  Current  Tasks  --> 

7 @if  (count(Stasks)  > 0) 

8 <div  class="panel  panel -default" > 

9 <div  class="panel -heading" > 

10  Current  Tasks 

11  </div> 

12 

13  <div  class="panel -body " > 

14  <table  class="table  table-striped  task-table"> 

15 

16  <!--  Table  Headings  --> 

17  <thead> 

18  <th>Task</th> 

19  <th>&nbsp; </th> 

20  </thead> 

21 
22 


< ! --  Table  Body  --> 
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23 

<tbody> 

24 

§foreach  ($tasks  as  $task) 

25 

<tr> 

26 

< ! - - Task  Name  - - > 

27 

<td  class="table-text' 

’> 

28 

<div>{{  $task->name  }}</div> 

29 

</td> 

30 

31 

<td> 

32 

<!--  TODO:  Delete 

Button  --> 

33 

</td> 

34 

</tr> 

35 

§endforeach 

36 

</tbody> 

37 

</table> 

38 

</div> 

39 

</div> 

40 

@endi f 

41 

@endsection 

Our  task  application  is  almost  complete.  But,  we  have  no  way  to  delete  our  existing  tasks  when 
they’re  done.  Let’s  add  that  next! 


Deleting  Tasks 

Adding  The  Delete  Button 


We  left  a “TODO”  note  in  our  code  where  our  delete  button  is  supposed  to  be.  So,  let’s  add  a delete 
button  to  each  row  of  our  task  listing  within  the  tasks/ index . blade . php  view.  We’ll  create  a small 
single-button  form  for  each  task  in  the  list.  When  the  button  is  clicked,  a DELETE  /task  request  will 
be  sent  to  the  application  which  will  trigger  our  TaskController@destroy  method: 


1 <tr> 

2 < ! - - Task  Name  --> 

<td  c 1 ass=" table- text "> 

4 <div>/Y  $task->name  jj</div> 

5 </td> 

6 

7 

8 


</--  Delete  Button  --> 

<td> 
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<form  action="/Y  url( 'task/' ,$task->id)  }}"  method="POST"> 


10 

{!! 

csrf_f ield( ) ! ! } 

11 

{!! 

method_field( 'DELETE' ) !!} 

12 

13 

<button>Delete  Task</button> 

14 

</form> 

15 

</td> 

16 

</tr> 

A Note  On  Method  Spoofing 

Note  that  the  delete  button’s  form  method  is  listed  as  POST,  even  though  we  are  responding  to  the 
request  using  a Route : : delete  route.  HTML  forms  only  allow  the  GET  and  POST  HTTP  verbs,  so  we 
need  a way  to  spoof  a DELETE  request  from  the  form. 

We  can  spoof  a DELETE  request  by  outputting  the  results  of  the  method_f  ield(  ' DELETE ' ) function 
within  our  form.  This  function  generates  a hidden  form  input  that  Laravel  recognizes  and  will  use 
to  override  the  actual  HTTP  request  method.  The  generated  field  will  look  like  the  following: 


1 <input  type="hidden"  name="_method"  value="DELETE"> 


Route  Model  Binding 

Now,  we’re  almost  ready  to  define  the  destroy  method  on  our  TaskControl  ler.  But,  first,  let’s  revisit 
our  route  declaration  and  controller  method  for  this  route: 


1 Route :: delete( ' /task/{task} ' , ' TaskControl ler@destroy ') ; 

2 

3 /** 

4 * Destroy  the  given  task. 

5 * 

6 * §param  Request  $ request 

7 * §param  Task  $task 

8 * §return  Response 

9 V 

10  public  function  destroy (Request  $request,  Task  $task) 

11  { 

12  // 
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13  } 


Since  the  {task}  variable  in  our  route  matches  the  $task  variable  defined  in  our  controller  method, 
Laravel’s  implicit  model  binding  will  automatically  inject  the  corresponding  Task  model  instance. 

Authorization 

Now,  we  have  a Task  instance  injected  into  our  destroy  method;  however,  we  have  no  guarantee 
that  the  authenticated  user  actually  “owns”  the  given  task.  For  example,  a malicious  request  could 
have  been  concocted  in  an  attempt  to  delete  another  user’s  tasks  by  passing  a random  task  ID  to 
the  /tasks/{task}  URL.  So,  we  need  to  use  Laravel’s  authorization  capabilities  to  make  sure  the 
authenticated  user  actually  owns  the  Task  instance  that  was  injected  into  the  route. 

Creating  A Policy 

Laravel  uses  “policies”  to  organize  authorization  logic  into  simple,  small  classes.  Typically,  each 
policy  corresponds  to  a model.  So,  let’s  create  a TaskPol  icy  using  the  Artisan  CLI,  which  will  place 
the  generated  fde  in  app/Pol  icies/TaskPol  icy . php: 


1 php  artisan  make: policy  TaskPol icy 


Next,  let’s  add  a destroy  method  to  the  policy.  This  method  will  receive  a User  instance  and  a Task 
instance.  The  method  should  simply  check  if  the  user’s  ID  matches  the  user_id  on  the  task.  In  fact, 
all  policy  methods  should  either  return  true  or  false: 


1 < ?php 

2 

3 namespace  App\Pol icies; 

4 

5 use  App\User; 

6 use  App\Task; 

7 use  1 1 luminate\Auth\Access\HandlesAuthorization; 

8 

9  class  TaskPolicy 

10  { 

11  use  HandlesAuthorization; 

12 

13  /** 

14  * Determine  if  the  given  user  can  delete  the  given  task. 
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15  * 

16  * §param  User  $user 

17  * §param  Task  $task 

18  * §return  bool 

19  V 

20  public  function  destroy(User  $user,  Task  $task) 

21  { 

return  $user->id  ===  $task- >user_id; 

23  } 

24  } 


Finally,  we  need  to  associate  our  Task  model  with  our  TaskPol  icy.  We  can  do  this  by  adding  a line  in 
the  app/Providers/AuthServiceProvider . php  file’s  $policies  property  This  will  inform  Laravel 
which  policy  should  be  used  whenever  we  try  to  authorize  an  action  on  a Task  instance: 


1 /** 

2 * The  policy  mappings  for  the  application. 

3 * 

4 * @var  array 

5 V 

6 protected  Spolicies  = [ 

'App\Task'  =>  1 2 3 4 5 6 7 8 9 App\Pol icies\TaskPol icy ' , 

8 ]; 


Authorizing  The  Action 

Now  that  our  policy  is  written,  let’s  use  it  in  our  destroy  method.  All  Laravel  controllers  may  call 
an  authorize  method,  which  is  exposed  by  the  Author izesRequest  trait: 


1 /** 

2 * Destroy  the  given  task. 

3 * 

4 * §param  Request  $request 

5 * §param  Task  $task 

6 * §return  Response 

7 V 

8 public  function  destroy (Request  Srequest,  Task  $task) 

9 { 
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$this- >author ize( 'destroy' , $task); 

11 

//  Delete  The  Task. . . 

13  } 


Let’s  examine  this  method  call  for  a moment.  The  first  argument  passed  to  the  authorize  method 
is  the  name  of  the  policy  method  we  wish  to  call.  The  second  argument  is  the  model  instance  that 
is  our  current  concern.  Remember,  we  recently  told  Laravel  that  our  Task  model  corresponds  to  our 
TaskPol  icy,  so  the  framework  knows  on  which  policy  to  fire  the  destroy  method.  The  current  user 
will  automatically  be  sent  to  the  policy  method,  so  we  do  not  need  to  manually  pass  it  here. 

If  the  action  is  authorized,  our  code  will  continue  executing  normally.  However,  if  the  action  is  not 
authorized  (meaning  the  policy’s  destroy  method  returned  false),  a 403  exception  will  be  thrown 
and  an  error  page  will  be  displayed  to  the  user. 


Note:  There  are  several  other  ways  to  interact  with  the  authorization  services  Laravel 
provides.  Be  sure  to  browse  the  complete  authorization  documentation. 


Deleting  The  Task 

Finally,  let’s  finish  adding  the  logic  to  our  destroy  method  to  actually  delete  the  given  task.  We  can 
use  Eloquent’s  delete  method  to  delete  the  given  model  instance  in  the  database.  Once  the  record 
is  deleted,  we  will  redirect  the  user  back  to  the  /tasks  URL: 

1 /** 

2 * Destroy  the  given  task. 

3 * 

4 * §param  Request  $request 

5 * §param  Task  $task 

6 * &return  Response 

7 V 

8 public  function  destroy (Request  Srequest,  Task  $task) 

9 { 


10 

$this- > author ize( 

'destroy',  $task); 

11 

12 

$task- >delete( ) ; 

13 

14 

return  redirect!' 

/tasks ' ) ; 

Intermediate  Task  List 
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15  } 
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Basic  Routing 


All  Faravel  routes  are  defined  in  the  app/Http/routes . php  file,  which  is  automatically  loaded  by 
the  framework.  The  most  basic  Faravel  routes  simply  accept  a URI  and  a Closure,  providing  a very 
simple  and  expressive  method  of  defining  routes: 


1 

Route : : get( 

foo ' , 

function  ()  { 

2 

return 

Hello 

World ’ ; 

3 

}); 

The  Default  Routes  File 

By  default,  the  routes . php  file  contains  a single  route  as  well  as  a route  group  that  applies  the  web 
middleware  group  to  all  routes  it  contains.  This  middleware  group  provides  session  state  and  CSRF 
protection  to  routes. 

Any  routes  not  placed  within  the  web  middleware  group  will  not  have  access  to  sessions  and  CSRF 
protection,  so  make  sure  any  routes  that  need  these  features  are  placed  within  the  group.  Typically, 
you  will  place  most  of  your  routes  within  this  group: 
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1 Route :: group( [' middleware ' =>  ['web']],  function  ()  { 

2 // 

3 }); 


Available  Router  Methods 

The  router  allows  you  to  register  routes  that  respond  to  any  HTTP  verb: 

1 Route :: get($uri , $callback); 

2 Route :: post($uri , $callback); 

3 Route :: put($uri , $callback); 

4 Route :: patch($uri , $callback); 

5 Route :: delete($uri , $callback); 

6 Route: :options($uri,  $callback); 


Sometimes  you  may  need  to  register  a route  that  responds  to  multiple  HTTP  verbs.  You  may  do  so 
using  the  match  method.  Or,  you  may  even  register  a route  that  responds  to  all  HTTP  verbs  using 
the  any  method: 

1 Route :: match( [' get 1 , 'post'],  '/',  function  ()  { 

2 // 

3 }); 

4 

5 Route :: any (' foo ' , function  ()  { 

6 // 

7 }); 


Route  Parameters 

Required  Parameters 

Of  course,  sometimes  you  will  need  to  capture  segments  of  the  URI  within  your  route.  For  example, 
you  may  need  to  capture  a user’s  ID  from  the  URL.  You  may  do  so  by  defining  route  parameters: 
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1  Route :: get( ' user/{ id} ' , function  ($id)  { 
return  ' User  ' . $id; 

3 }); 


You  may  define  as  many  route  parameters  as  required  by  your  route: 


1 Route :: get( ' posts/{post}/comments/{comment} ' , function  (Ipostld,  $commentId)  { 

2 // 

3 }); 


Route  parameters  are  always  encased  within  “curly”  braces.  The  parameters  will  be  passed  into  your 
route’s  Closure  when  the  route  is  executed. 


Note:  Route  parameters  cannot  contain  the  - character.  Use  an  underscore  (_)  instead. 


Optional  Parameters 


Occasionally  you  may  need  to  specify  a route  parameter,  but  make  the  presence  of  that  route 
parameter  optional.  You  may  do  so  by  placing  a ? mark  after  the  parameter  name.  Make  sure  to 
give  the  route’s  corresponding  variable  a default  value: 


1 

Route : : get( ' user/{name?} ' 

function 

($name  = null)  { 

2 

return  $name; 

3 

}); 

4 

5 

Route : : get( ' user/{name?} ' 

function 

($name  = ' John ' ) { 

6 

return  $name; 

7 

}); 

Named  Routes 

Named  routes  allow  the  convenient  generation  of  URLs  or  redirects  for  specific  routes.  You  may 
specify  a name  for  a route  using  the  as  array  key  when  defining  the  route: 
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1 Route :: get( ' prof i le ' , ['as'  =>  'profile',  function  ()  { 

2 // 

3 }]); 


You  may  also  specify  route  names  for  controller  actions: 

1 Route :: get( ' prof i le ' , [ 

'as'  =>  'profile',  'uses'  =>  ' UserControl ler@showProf i le ' 

3 ]); 


Alternatively,  instead  of  specifying  the  route  name  in  the  route  array  definition,  you  may  chain  the 
name  method  onto  the  end  of  the  route  definition: 


1 Route : : get( ' user/profile' , ' UserControl ler§showProfi le ' ) - >name( ' prof i le ' ) ; 


Route  Groups  & Named  Routes 

If  you  are  using  route  groups,  you  may  specify  an  as  keyword  in  the  route  group  attribute  array, 
allowing  you  to  set  a common  route  name  prefix  for  all  routes  within  the  group: 

1 Route :: group( [' as ' =>  'admin::'],  function  ()  { 

Route :: get( ' dashboard ' , ['as'  =>  'dashboard',  function  ()  { 

//  Route  named  "admin :: dashboard" 

4 }]); 

5 }); 


Generating  URLs  To  Named  Routes 

Once  you  have  assigned  a name  to  a given  route,  you  may  use  the  route’s  name  when  generating 
URLs  or  redirects  via  the  global  route  function: 
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1 //  Generating  URLs... 

2 $url  = route( ' prof i le ' ) ; 

3 

4 //  Generating  Redirects... 

5 return  redirect( ) - >route( ' prof i le ' ) ; 


If  the  named  route  defines  parameters,  you  may  pass  the  parameters  as  the  second  argument  to  the 
route  function.  The  given  parameters  will  automatically  be  inserted  into  the  URL  in  their  correct 
positions: 


1 Route :: get( ' user/{ id}/profi le 1 , ['as'  =>  'profile',  function  (Sid)  { 

2 // 

3 }]); 

4 

5 $url  = route( ' prof i le ' , ['id'  =>  1]); 


Route  Groups 

Route  groups  allow  you  to  share  route  attributes,  such  as  middleware  or  namespaces,  across  a 
large  number  of  routes  without  needing  to  define  those  attributes  on  each  individual  route.  Shared 
attributes  are  specified  in  an  array  format  as  the  first  parameter  to  the  Route : : group  method. 

To  learn  more  about  route  groups,  we’ll  walk  through  several  common  use-cases  for  the  feature. 


Middleware 

To  assign  middleware  to  all  routes  within  a group,  you  may  use  the  middleware  key  in  the  group 
attribute  array  Middleware  will  be  executed  in  the  order  you  define  this  array: 
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1 Route :: group( [' middleware ' =>  'auth'],  function  ()  { 
Route :: get( '/'  , function  ()  { 

//  Uses  Auth  Middleware 

4 }); 

5 

Route :: get( 1 user/prof i le 1 , function  ()  { 

//  Uses  Auth  Middleware 

8 }); 

9 }); 


Namespaces 


Another  common  use-case  for  route  groups  is  assigning  the  same  PHP  namespace  to  a group  of 
controllers.  You  may  use  the  namespace  parameter  in  your  group  attribute  array  to  specify  the 
namespace  for  all  controllers  within  the  group: 


1 

Route :: group( [’ namespace 1 => 

'Admin'],  function() 

2 

{ 

3 

4 

//  Controllers  Within  The 

"App\Http\Control lers\Admin"  Namespace 

5 

Route : : group( [ 1 namespace  1 

=>  'User'],  functionQ  { 

6 

//  Controllers  Within 

The  "App\Http\Control lers\Admin\User " Namespace 

7 

1); 

8 

}); 

Remember,  by  default,  the  RouteServiceProvider  includes  your  routes . php  file  within  a names- 
pace group,  allowing  you  to  register  controller  routes  without  specifying  the  full  App  \Http  \Contro  tiers 
namespace  prefix.  So,  we  only  need  to  specify  the  portion  of  the  namespace  that  comes  after  the  base 
App\Http\Control  lers  namespace. 

Sub-Domain  Routing 

Route  groups  may  also  be  used  to  route  wildcard  sub-domains.  Sub-domains  may  be  assigned  route 
parameters  just  like  route  URIs,  allowing  you  to  capture  a portion  of  the  sub-domain  for  usage 
in  your  route  or  controller.  The  sub-domain  may  be  specified  using  the  domain  key  on  the  group 
attribute  array: 
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1 Route :: group( [' domain ' =>  ' {account} . myapp . com '] , function  ()  { 
Route :: get( ' user/{ id} ' , function  ($account,  $id)  { 

3 // 

4 }); 

5 }); 


Route  Prefixes 

The  prefix  group  attribute  may  be  used  to  prefix  each  route  in  the  group  with  a given  URL  For 
example,  you  may  want  to  prefix  all  route  URIs  within  the  group  with  admin: 


1 Route :: group( [’ prefix 1 =>  ’admin'],  function  ()  { 
Route :: get (' users ' , function  ()  { 

//  Matches  The  "/admin/users"  URL 

4 }); 

5 }); 


You  may  also  use  the  prefix  parameter  to  specify  common  parameters  for  your  grouped  routes: 

1 Route :: group( [' prefix ' =>  ' accounts/{account_id} ' ] , function  ()  { 

Route: : get( 'detail ' , function  (Saccountld)  { 

//  Matches  The  "/accounts/{account_id}/detai 1 " URL 

4 }); 

5 }); 


CSRF  Protection 

Introduction 

Laravel  makes  it  easy  to  protect  your  application  from  cross-site  request  forgery53  (CSRF)  attacks. 
Cross-site  request  forgeries  are  a type  of  malicious  exploit  whereby  unauthorized  commands  are 
performed  on  behalf  of  an  authenticated  user. 

53http://en.  wikipedia.org/wiki/  Cross-  site_request_forgery 
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Laravel  automatically  generates  a CSRF  “token”  for  each  active  user  session  managed  by  the 
application.  This  token  is  used  to  verify  that  the  authenticated  user  is  the  one  actually  making  the 
requests  to  the  application. 

Anytime  you  define  a HTML  form  in  your  application,  you  should  include  a hidden  CSRF  token  field 
in  the  form  so  that  the  CSRF  protection  middleware  will  be  able  to  validate  the  request.  To  generate  a 
hidden  input  field  _token  containing  the  CSRF  token,  you  may  use  the  csr f_f ield  helper  function: 


1 //  Vanilla  PHP 

2 <?php  echo  csr f_f ield( ) ; ?> 

3 

4 //  Blade  Template  Syntax 

5 {{  csr f_f ield( ) }} 


The  csr f_f  ield  helper  function  generates  the  following  HTML: 

1 cinput  type="hidden"  name~"_token"  value=" <?php  echo  csrf_token( ) ; ?>"> 


You  do  not  need  to  manually  verify  the  CSRF  token  on  POST,  PUT,  or  DELETE  requests.  The 
VerifyCsrf Token  middleware,  which  is  included  in  the  web  middleware  group,  will  automatically 
verify  that  the  token  in  the  request  input  matches  the  token  stored  in  the  session. 

Excluding  URIs  From  CSRF  Protection 

Sometimes  you  may  wish  to  exclude  a set  of  URIs  from  CSRF  protection.  For  example,  if  you  are 
using  Stripe54  to  process  payments  and  are  utilizing  their  webhook  system,  you  will  need  to  exclude 
your  webhook  handler  route  from  Laravel’s  CSRF  protection. 

You  may  exclude  URIs  by  defining  their  routes  outside  of  the  web  middleware  group  that  is  included 
in  the  default  routes . php  file,  or  by  adding  the  URIs  to  the  $except  property  of  the  Ver  i fyCsrf  Token 
middleware: 


54https://stripe.com 
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1 < ?php 

2 

3 namespace  App\Http\Middleware; 

4 

5 use  1 1 luminate\Foundation\Http\Middleware\Veri fyCsrfToken  as  BaseVer i f ier ; 

6 

7 class  Veri fyCsrfToken  extends  BaseVer if ier 

8 { 

9 /** 

10  * The  UR  Is  that  should  be  excluded  from  CSRF  verification . 

11  * 

12  * §var  array 

13  V 

14  protected  $except  [ 

15  1 stripe/* ' , 

16  ]; 

17  } 


X-CSRF-TOKEN 

In  addition  to  checking  for  the  CSRF  token  as  a POST  parameter,  the  Laravel  Veri  fyCsrfToken 
middleware  will  also  check  for  the  X-CSRF-TOKEN  request  header.  You  could,  for  example,  store  the 
token  in  a “meta”  tag: 


1 <meta  name="csr f-token"  content=" {{  csrf_token()  }}"> 


Once  you  have  created  the  meta  tag,  you  can  instruct  a library  like  jQuery  to  add  the  token 
to  all  request  headers.  This  provides  simple,  convenient  CSRF  protection  for  your  AJAX  based 
applications: 

1 $ . ajaxSetup( { 

headers:  { 

' X-CSRF-TOKEN ' : $( 1 meta [name="csr f-token" ] ' ) ■ attr( ' content 1 ) 

4 } 

5 }); 
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X-XSRF-TOKEN 

Laravel  also  stores  the  CSRF  token  in  a XSRF-TOKEN  cookie.  You  can  use  the  cookie  value  to  set  the 
X-XSRF-TOKEN  request  header.  Some  JavaScript  frameworks,  like  Angular,  do  this  automatically  for 
you.  It  is  unlikely  that  you  will  need  to  use  this  value  manually. 

Route  Model  Binding 

Laravel  route  model  binding  provides  a convenient  way  to  inject  model  instances  into  your  routes. 
For  example,  instead  of  injecting  a user’s  ID,  you  can  inject  the  entire  User  model  instance  that 
matches  the  given  ID. 

Implicit  Binding 

Laravel  will  automatically  resolve  type-hinted  Eloquent  model’s  defined  in  routes  or  controller 
actions  whose  variable  names  match  a route  segment  name.  For  example: 

1 Route :: get( ' api/users/{user }' , function  (App\User  $user)  { 
return  $user- >emai 1 ; 

3 }); 


In  this  example,  since  the  Eloquent  type-hinted  $user  variable  defined  on  the  route  matches  the 
{user}  segment  in  the  route’s  URI,  Laravel  will  automatically  inject  the  model  instance  that  has  an 
ID  matching  the  corresponding  value  from  the  request  URI. 

If  a matching  model  instance  is  not  found  in  the  database,  a 404  HTTP  response  will  be  automatically 
generated. 

Customizing  The  Key  Name 

If  you  would  like  the  implicit  model  binding  to  use  a database  column  other  than  id  when  retrieving 
models,  you  may  override  the  getRouteKeyName  method  on  your  Eloquent  model: 
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1  /** 

2 * Get  the  route  key  for  the  model . 

3 * 

4 * §return  string 

5 V 

6 public  function  getRouteKeyName( ) 

7 { 

return  ' slug ' ; 

9 } 


Explicit  Binding 

To  register  an  explicit  binding,  use  the  router’s  model  method  to  specify  the  class  for  a given 
parameter.  You  should  define  your  model  bindings  in  the  RouteServiceProvider : : boot  method: 

Binding  A Parameter  To  A Model 


1 public  function  boot(Router  $router) 

2 { 

parent : : boot( $router ) ; 

4 

$router- > model ( 1 user ' , ' App\User ' ) ; 

6 } 


Next,  define  a route  that  contains  a {user}  parameter: 

1 $router->get( ' prof i le/{user} ' , function( App\User  $user)  { 

2 // 

3 }); 


Since  we  have  bound  the  {user}  parameter  to  the  App\User  model,  a User  instance  will  be  injected 
into  the  route.  So,  for  example,  a request  to  profile/1  will  inject  the  User  instance  which  has  an  ID 
of  1. 

If  a matching  model  instance  is  not  found  in  the  database,  a 404  HTTP  response  will  be  automatically 
generated. 
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Customizing  The  Resolution  Logic 

If  you  wish  to  use  your  own  resolution  logic,  you  should  use  the  Route : : bind  method.  The  Closure 
you  pass  to  the  b i nd  method  will  receive  the  value  of  the  URI  segment,  and  should  return  an  instance 
of  the  class  you  want  to  be  injected  into  the  route: 


1 $router->bind( 'user' , function($value)  { 

return  App\User : : where( ' name  1 * * 4 , lvalue) -> first( ) ; 

3 }); 


Customizing  The  "Not  Found"  Behavior 

If  you  wish  to  specify  your  own  “not  found”  behavior,  pass  a Closure  as  the  third  argument  to  the 
model  method: 

1 $router- >model ( ' user ' , 'App\User',  function! ) { 
throw  new  NotFoundHttpException; 

3 }); 


Form  Method  Spoofing 

HTML  forms  do  not  support  PUT,  PATCH  or  DELETE  actions.  So,  when  defining  PUT,  PATCH  or  DELETE 
routes  that  are  called  from  an  HTML  form,  you  will  need  to  add  a hidden  _method  field  to  the  form. 
The  value  sent  with  the  _method  field  will  be  used  as  the  HTTP  request  method: 


1 <form  action="/foo/bar"  method="POST" > 

<input  type="hidden"  name="_method"  value="PUT"> 

<input  type="hidden"  name="_token"  value="/Y  csrf_token()  }}"> 

4 </form> 


To  generate  the  hidden  input  field  _method,  you  may  also  use  the  method_field  helper  function: 


1 <?php  echo  method_f ield( ' PUT ' ) ; ?> 
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Of  course,  using  the  Blade  templating  engine: 


1 {{  method_f ield( ' PUT  1 ) }} 


Accessing  The  Current  Route 

The  Route:  : cur  rent  ( ) method  will  return  the  route  handling  the  current  HTTP  request,  allowing 
you  to  inspect  the  full  Illuminate\Routing\Route  instance: 


1 $route  = Route :: current( ) ; 

2 

3 $name  = $route- >getName( ) ; 

4 

5 SactionName  = $route- >getActionName( ) ; 


You  may  also  use  the  currentRouteName  and  currentRouteAction  helper  methods  on  the  Route 
facade  to  access  the  current  route’s  name  or  action: 


1 $name  = Route :: currentRouteName( ) ; 

2 

3 Saction  = Route :: currentRouteAction( ) ; 


Please  refer  to  the  API  documentation  for  both  the  underlying  class  of  the  Route  facade55  and  Route 
instance56  to  review  all  accessible  methods. 

55http://laravel.com/api/\protect\char”007B\relax\protect\char”007B\relaxversion\protect\char”007D\relax\protect\char”007D\relax/Illuminate/ 

Routing/Router.html 

56http://laravel.com/api/\protect\char”007B\relax\protect\char”007B\relaxversion\protect\char”007D\relax\protect\char”007D\relax/Illuminate/ 

Routing/Route.html 
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Introduction 

HTTP  middleware  provide  a convenient  mechanism  for  filtering  HTTP  requests  entering  your 
application.  For  example,  Laravel  includes  a middleware  that  verifies  the  user  of  your  application 
is  authenticated.  If  the  user  is  not  authenticated,  the  middleware  will  redirect  the  user  to  the  login 
screen.  However,  if  the  user  is  authenticated,  the  middleware  will  allow  the  request  to  proceed 
further  into  the  application. 

Of  course,  additional  middleware  can  be  written  to  perform  a variety  of  tasks  besides  authentication. 
A CORS  middleware  might  be  responsible  for  adding  the  proper  headers  to  all  responses  leaving  your 
application.  A logging  middleware  might  log  all  incoming  requests  to  your  application. 

There  are  several  middleware  included  in  the  Laravel  framework,  including  middleware  for 
maintenance,  authentication,  CSRF  protection,  and  more.  All  of  these  middleware  are  located  in 
the  app/Http/Middleware  directory. 

Defining  Middleware 

To  create  a new  middleware,  use  the  make : middleware  Artisan  command: 


1 php  artisan  make : middleware  AgeMiddleware 


This  command  will  place  a new  AgeMiddleware  class  within  your  app/Http/Middleware  directory. 
In  this  middleware,  we  will  only  allow  access  to  the  route  if  the  supplied  age  is  greater  than  200. 
Otherwise,  we  will  redirect  the  users  back  to  the  “home”  URL 
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1 < ?php 

2 

3 namespace  App\Http\Middleware; 

4 

5 use  Closure; 

6 

7 class  AgeMiddleware 

8 { 

g /** 

10  * Run  the  request  filter. 

11  * 

12  * §param  \Illuminate\Http\Request  $request 

13  * §param  \Closure  $next 

14  * §return  mixed 

15  */ 

public  function  handle($request,  Closure  $next) 

17  { 

18  if  (Srequest- > input( ' age ' ) <=  200)  { 

19  return  red i rect (' home ') ; 

20  } 

21 

22  return  $next($request) ; 

23  } 

24 

25  } 


As  you  can  see,  if  the  given  age  is  less  than  or  equal  to  200,  the  middleware  will  return  an  HTTP 
redirect  to  the  client;  otherwise,  the  request  will  be  passed  further  into  the  application.  To  pass 
the  request  deeper  into  the  application  (allowing  the  middleware  to  “pass”),  simply  call  the  $next 
callback  with  the  $request. 

It’s  best  to  envision  middleware  as  a series  of  “layers”  HTTP  requests  must  pass  through  before  they 
hit  your  application.  Each  layer  can  examine  the  request  and  even  reject  it  entirely. 

Before  / After  Middleware 

Whether  a middleware  runs  before  or  after  a request  depends  on  the  middleware  itself.  For  example, 
the  following  middleware  would  perform  some  task  before  the  request  is  handled  by  the  application: 
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1 < ?php 

2 

3 namespace  App\Http\Middleware; 

4 

5 use  Closure; 

6 

7 class  BeforeMiddleware 

8 { 

public  function  handle($request,  Closure  $next) 


10 

{ 

11 

//  Perform  action 

12 

13 

return  $next($request) ; 

14 

1 

15  } 

However,  this  middleware  would  perform  its  task  after  the  request  is  handled  by  the  application: 


1 < ?php 

2 

3 namespace  App\Http\Middleware; 

4 

5 use  Closure; 

6 

7 class  AfterMiddleware 

8 { 

public  function  handle($request,  Closure  $next) 


10 

1 

11 

Sresponse  = $next($request) ; 

12 

13 

//  Perform  action 

14 

15 

return  $response; 

16 

1 

17  } 
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Registering  Middleware 

Global  Middleware 

If  you  want  a middleware  to  be  run  during  every  HTTP  request  to  your  application,  simply  list  the 
middleware  class  in  the  $middleware  property  of  your  app/Http/Kernel . php  class. 

Assigning  Middleware  To  Routes 

If  you  would  like  to  assign  middleware  to  specific  routes,  you  should  first  assign  the  middleware 
a short-hand  key  in  your  app/Http/Kernel . php  file.  By  default,  the  SrouteMiddleware  property 
of  this  class  contains  entries  for  the  middleware  included  with  Laravel.  To  add  your  own,  simply 
append  it  to  this  list  and  assign  it  a key  of  your  choosing.  For  example: 

1 //  Within  App\Http\Kernel  Class... 

2 

3 protected  SrouteMiddleware  = [ 

4 'auth'  =>  \App\Http\Middleware\Authenticate: :class, 

'auth. basic'  =>  \I 1 luminate\Auth\Middleware\AuthenticateWithBasicAuth : :class, 

6 'guest'  =>  \App\Http\Middleware\RedirectI fAuthenticated : :class, 

'throttle'  =>  \I1 luminate\Routing\Middleware\ThrottleRequests : :class, 

8 1; 


Once  the  middleware  has  been  defined  in  the  HTTP  kernel,  you  may  use  the  middleware  key  in  the 
route  options  array: 

1 Route :: get( ' admin/prof i le ' , ['middleware'  =>  'auth',  function  ()  { 

2 // 

3 }]); 


Use  an  array  to  assign  multiple  middleware  to  the  route: 

1 Route :: get( '/' , ['middleware'  =>  ['first',  'second'],  function  ()  { 

2 // 

3 }]); 


Instead  of  using  an  array,  you  may  also  chain  the  middleware  method  onto  the  route  definition: 


HTTP  Middleware 


126 


1 Route :: get( , function  ()  { 

2 // 

3 })- >middleware( [' first ' , 'second']); 


Middleware  Groups 

Sometimes  you  may  want  to  group  several  middleware  under  a single  key  to  make  them  easier  to 
assign  to  routes.  You  may  do  this  using  the  SmiddlewareGroups  property  of  your  HTTP  kernel. 

Out  of  the  box,  Laravel  comes  with  web  and  api  middleware  groups  that  contains  common 
middleware  you  may  want  to  apply  to  web  UI  and  your  API  routes: 

1 /** 

2 * The  application's  route  middleware  groups. 

3 * 

4 * §var  array 

5 V 

6 protected  SmiddlewareGroups  = [ 

'web'  =>  [ 

\App\Http\Middleware\EncryptCookies : : class, 

\I 1 luminate\Cookie\Middleware\AddQueuedCookiesToResponse : : class, 

\I 1 luminate\Session\Middleware\StartSession : : class, 

\I 1 luminate\View\Middleware\ShareErrorsFromSession : : class, 
\App\Http\Middleware\Veri fyCsrfloken : : class , 

1, 

'api'  =>  [ 

' throttle : 60, 1 ' , 

' auth : api ' , 

], 


7 

8 
9 

10 

11 

12 

13 

14 

15 

16 

17 

18 

19  ]; 


Middleware  groups  may  be  assigned  to  routes  and  controller  actions  using  the  same  syntax  as 
individual  middleware.  Again,  middleware  groups  simply  make  it  more  convenient  to  assign  many 
middleware  to  a route  at  once: 
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1 Route :: group( [' middleware ' =>  ['web']],  function  ()  { 

2 // 

3 }); 


Middleware  Parameters 

Middleware  can  also  receive  additional  custom  parameters.  For  example,  if  your  application  needs 
to  verify  that  the  authenticated  user  has  a given  “role”  before  performing  a given  action,  you  could 
create  a RoleMiddleware  that  receives  a role  name  as  an  additional  argument. 

Additional  middleware  parameters  will  be  passed  to  the  middleware  after  the  $next  argument: 

1 < ?php 

2 

3 namespace  App\Http\Middleware; 

4 

5 use  Closure; 

6 

7 class  RoleMiddleware 

8 { 

g /** 

10  * Run  the  request  filter. 

11  * 

12  * §param  \Illuminate\Http\Request  $request 

13  * §param  \Closure  $next 

14  * §param  string  $role 

15  * §return  mixed 

16  */ 

17  public  function  handle($request,  Closure  $next,  $role) 

18  { 

19  if  (!  $request->user( )->hasRole($role))  { 

20  //  Redirect. . . 

21  } 

22 

23  return  $next($request) ; 

24  } 

25 

26  } 


HTTP  Middleware 


128 


Middleware  parameters  may  be  specified  when  defining  the  route  by  separating  the  middleware 
name  and  parameters  with  a : . Multiple  parameters  should  be  delimited  by  commas: 


1 Route :: put( ' post/{ id} ' , ['middleware'  =>  ' role : editor ' , function  (lid)  { 

2 // 

3 }]); 


Terminable  Middleware 

Sometimes  a middleware  may  need  to  do  some  work  after  the  HTTP  response  has  already  been  sent 
to  the  browser.  For  example,  the  “session”  middleware  included  with  Laravel  writes  the  session  data 
to  storage  after  the  response  has  been  sent  to  the  browser.  To  accomplish  this,  define  the  middleware 
as  “terminable”  by  adding  a terminate  method  to  the  middleware: 

1 < ?php 

2 

3 namespace  1 1 luminate\Session\Middleware; 

4 

5 use  Closure; 

6 

7 class  StartSession 

8 { 

public  function  handle($request,  Closure  Inext) 

10  { 

11  return  Inext(lrequest) ; 

12  } 

13 

14  public  function  terminate($request,  Sresponse) 

15  { 

16  //  Store  the  session  data. . . 

17  } 

18  } 


The  terminate  method  should  receive  both  the  request  and  the  response.  Once  you  have  defined  a 
terminable  middleware,  you  should  add  it  to  the  list  of  global  middlewares  in  your  HTTP  kernel. 

When  calling  the  terminate  method  on  your  middleware,  Laravel  will  resolve  a fresh  instance  of 
the  middleware  from  the  service  container.  If  you  would  like  to  use  the  same  middleware  instance 
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when  the  handle  and  terminate  methods  are  called,  register  the  middleware  with  the  container 
using  the  container’s  singleton  method. 
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• Controller  Middleware 
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- Supplementing  Resource  Controllers 

• Dependency  Injection  & Controllers 

• Route  Caching 

Introduction 

Instead  of  defining  all  of  your  request  handling  logic  in  a single  routes . php  file,  you  may  wish 
to  organize  this  behavior  using  Controller  classes.  Controllers  can  group  related  HTTP  request 
handling  logic  into  a class.  Controllers  are  stored  in  the  app/Http/Control  lers  directory. 

Basic  Controllers 

Here  is  an  example  of  a basic  controller  class.  All  Laravel  controllers  should  extend  the  base 
controller  class  included  with  the  default  Laravel  installation: 


1 < ?php 

2 

3 namespace  App\Http\Control lers; 

4 

5 use  App\User; 

6 use  App\Http\Controllers\Controller; 

7 

8 class  UserController  extends  Controller 

9 { 

10  /** 

11  * Show  the  profile  for  the  given  user. 

12  * 

13  * @param  int  $id 

14  * §return  Response 

15  */ 

16  public  function  showProf i le($id) 

17  { 
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return  view( 1 user . prof i le ' , [ user'  =>  User  : f indOrFai 1 ($id ) ] ) ; 

19  } 

20  } 


We  can  route  to  the  controller  action  like  so: 

1 Route :: get( ' user/{ id} ' , ' UserControl ler(g>showProf i le 1 ) ; 


Now,  when  a request  matches  the  specified  route  URI,  the  showProfile  method  on  the  UserCon- 
trol ler  class  will  be  executed.  Of  course,  the  route  parameters  will  also  be  passed  to  the  method. 

Controllers  & Namespaces 

It  is  very  important  to  note  that  we  did  not  need  to  specify  the  full  controller  namespace  when 
defining  the  controller  route.  We  only  defined  the  portion  of  the  class  name  that  comes  after 
the  App\Http\Control  lers  namespace  “root”.  By  default,  the  RouteServiceProvider  will  load  the 
routes . php  file  within  a route  group  containing  the  root  controller  namespace. 

If  you  choose  to  nest  or  organize  your  controllers  using  PHP  namespaces  deeper  into  the  App\Http\Control  lers 
directory,  simply  use  the  specific  class  name  relative  to  the  App\Http\Control  lers  root  namespace. 

So,  if  your  full  controller  class  is  App\Http\Control lers \Photos\AdminControl ler,  you  would 
register  a route  like  so: 


1 Route :: get( ' foo ' , 1 Photos \AdminControl ler@method ') ; 


Naming  Controller  Routes 

Like  Closure  routes,  you  may  specify  names  on  controller  routes: 

1 Route :: get( ' foo ' , ['uses'  =>  ' FooControl ler§method ' , 'as'  =>  'name'J); 


You  may  also  use  the  route  helper  to  generate  a URL  to  a named  controller  route: 
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1  $url  = route( ' name  1 11 ) ; 


Controller  Middleware 

Middleware  may  be  assigned  to  the  controller’s  routes  like  so: 


1 Route :: get( ' prof i le ' , [ 

'middleware'  =>  'auth', 

'uses’  =>  ' UserControl  ler©showProf  i le  ' 

4 ]); 


However,  it  is  more  convenient  to  specify  middleware  within  your  controller’s  constructor.  Using 
the  middleware  method  from  your  controller’s  constructor,  you  may  easily  assign  middleware  to 
the  controller.  You  may  even  restrict  the  middleware  to  only  certain  methods  on  the  controller  class: 


1 class  UserControl ler  extends  Controller 

2 { 

3 /** 

* Instantiate  a new  UserControl ler  instance. 

5 * 

6 * ©return  void 

7 */ 

public  function  constructQ 

9 { 

10  $this- >middleware( ' auth ' ) ; 

11 

$this- >middleware( ' log ' , ['only'  =>  [ 

13  ' fooAction ' , 

14  'barAction', 

15  ]]); 

16 

17  $this- >middleware( ' subscribed ' , ['except'  =>  [ 

18  ' fooAction ' , 

19  'barAction', 

20  ]]); 
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21  } 
22  } 


RESTful  Resource  Controllers 

Resource  controllers  make  it  painless  to  build  RESTful  controllers  around  resources.  For  example, 
you  may  wish  to  create  a controller  that  handles  HTTP  requests  regarding  “photos”  stored  by  your 
application.  Using  the  make : control  ler  Artisan  command,  we  can  quickly  create  such  a controller: 


1 php  artisan  make : control ler  PhotoControl ler  --resource 


The  Artisan  command  will  generate  a controller  file  atapp/Http/Control  lers/PhotoControl  ler . php. 
The  controller  will  contain  a method  for  each  of  the  available  resource  operations. 

Next,  you  may  register  a resourceful  route  to  the  controller: 

1 Route :: resource! ' photo ' , 'PhotoControl ler ' ); 


This  single  route  declaration  creates  multiple  routes  to  handle  a variety  of  RESTful  actions  on  the 
photo  resource.  Likewise,  the  generated  controller  will  already  have  methods  stubbed  for  each  of 
these  actions,  including  notes  informing  you  which  URIs  and  verbs  they  handle. 

Actions  Handled  By  Resource  Controller 

| Verb  | Path  | Action  | Route  Name  | 1 1 1 | GET  | /photo  | 

index  | photo.index  1 1 GET  | /photo/create  | create  | photo. create  1 1 POST  | /photo  | store  | photo. store 
| GET  | /photo/{photo}  | show  | photo. show  | | GET  | /photo/{photo}/edit  | edit  | photo.edit  | 
PUT/PATCH  | /photo/{photo}  | update  | photo.update  | | DELETE  | /photo/{photo}  | destroy  | 
photo. destroy  | 

Partial  Resource  Routes 

When  declaring  a resource  route,  you  may  specify  a subset  of  actions  to  handle  on  the  route: 
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1 Route ::  resource(  ' photo ' , ' PhotoControl ler ' , ['only'  =>  [ 

' index ' , ' show  1 

3 ]]); 

4 

5 Route :: resource( ' photo ' , ' PhotoControl ler ' , ['except'  =>  [ 

6 'create',  'store',  'update',  'destroy' 

7 ]]); 


Naming  Resource  Routes 


By  default,  all  resource  controller  actions  have  a route  name;  however,  you  can  override  these  names 
by  passing  a names  array  with  your  options: 


1 

Route : : resource( ' photo ' , ' PhotoControl ler ' , 

[ ' names ' =>  [ 

2 

'create'  =>  ' photo . bui Id  ' 

3 

ID; 

Supplementing  Resource  Controllers 

If  it  becomes  necessary  to  add  additional  routes  to  a resource  controller  beyond  the  default  resource 
routes,  you  should  define  those  routes  before  your  call  to  Route : : resource;  otherwise,  the  routes 
defined  by  the  resource  method  may  unintentionally  take  precedence  over  your  supplemental 
routes: 


1 Route :: get( ' photos/popular ' , ' PhotoControl ler@method ') ; 

2 

3 Route :: resource (' photos ' , ' PhotoControl ler ') ; 


Dependency  Injection  & Controllers 

Constructor  Injection 

The  Laravel  service  container  is  used  to  resolve  all  Laravel  controllers.  As  a result,  you  are  able 
to  type-hint  any  dependencies  your  controller  may  need  in  its  constructor.  The  dependencies  will 
automatically  be  resolved  and  injected  into  the  controller  instance: 


HTTP  Controllers 


135 


1 < ?php 

2 

3 namespace  App\Http\Control lers; 

4 

5 use  App\Repositor ies\UserRepository ; 

6 

7 class  UserController  extends  Controller 

8 { 

g /** 

10  * The  user  repository  instance. 

11  */ 

12  protected  $users; 

13 

14  /** 

15  * Create  a new  controller  instance. 

16  * 

17  * §param  User Repository  $ users 

18  * §return  void 

19  */ 

public  function  construct(UserRepository  $users) 

21  { 

22  $this->users  = $users; 

23  } 

24  } 


Of  course,  you  may  also  type-hint  any  Laravel  contract.  If  the  container  can  resolve  it,  you  can 
type-hint  it. 

Method  Injection 

In  addition  to  constructor  injection,  you  may  also  type-hint  dependencies  on  your  controller’s  action 
methods.  For  example,  let’s  type-hint  the  1 1 luminate\Http\Request  instance  on  one  of  our  methods: 


1 < ?php 

2 

3 namespace  App\Http\Control lers; 

4 

5 use  1 1 luminate\Http\Request; 

6 

7 class  UserController  extends  Controller 

8 { 
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9 /** 

10  * Store  a new  user. 

11  * 

12  * §param  Request  $request 

13  * §return  Response 

14  V 

15  public  function  store(Request  Srequest) 

16  { 

17  $name  = Srequest- > input( ' name ') ; 

18 

19  // 

20  } 

21  } 


If  your  controller  method  is  also  expecting  input  from  a route  parameter,  simply  list  your  route 
arguments  after  your  other  dependencies.  For  example,  if  your  route  is  defined  like  so: 

1 Route :: put( ' user/{ id} ' , ' UserControl ler@update ' ) ; 


You  may  still  type-hint  the  Illuminate\Http\Request  and  access  your  route  parameter  id  by 
defining  your  controller  method  like  the  following: 


1 < ?php 

2 

3 namespace  App\Http\Control lers; 

4 

5 use  1 1 luminate\Http\Request; 

6 

7 class  UserControl ler  extends  Controller 

8 { 

g /** 

10  * Update  the  specified  user. 

11  * 

12  * §param  Request  Srequest 

13  * §param  string  $id 

14  * §return  Response 

15  V 

16  public  function  update(Request  Srequest,  Sid) 

17  { 
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18  // 

19  } 

20  } 


Route  Caching 


Note:  Route  caching  does  not  work  with  Closure  based  routes.  To  use  route  caching,  you 
must  convert  any  Closure  routes  to  use  controller  classes. 


If  your  application  is  exclusively  using  controller  based  routes,  you  should  take  advantage  of 
Laravel’s  route  cache.  Using  the  route  cache  will  drastically  decrease  the  amount  of  time  it  takes 
to  register  all  of  your  application’s  routes.  In  some  cases,  your  route  registration  may  even  be  up  to 
lOOx  faster!  To  generate  a route  cache,  just  execute  the  route : cache  Artisan  command: 


1 php  artisan  route: cache 


That’s  all  there  is  to  it!  Your  cached  routes  file  will  now  be  used  instead  of  your  app/Http/routes . php 
file.  Remember,  if  you  add  any  new  routes  you  will  need  to  generate  a fresh  route  cache.  Because  of 
this,  you  should  only  run  the  route : cache  command  during  your  project’s  deployment. 

To  remove  the  cached  routes  file  without  generating  a new  cache,  use  the  route : clear  command: 


1 php  artisan  route: clear 


HTTP  Requests 

• Accessing  The  Request  A>  - Basic  Request  Information  A>  - PSR-7  Requests 

• Retrieving  Input  A>  - Old  Input  A>  - Cookies  A>  - Files 

Accessing  The  Request 

To  obtain  an  instance  of  the  current  HTTP  request  via  dependency  injection,  you  should  type-hint 
the  1 1 luminate\Http\Request  class  on  your  controller  constructor  or  method.  The  current  request 
instance  will  automatically  be  injected  by  the  service  container: 


1 < ?php 

2 

3 namespace  App\Http\Control lers; 

4 

5 use  1 1 luminate\Http\Request; 

6 

7 class  UserController  extends  Controller 

8 { 

9 /** 

10  * Store  a new  user. 

11  * 

12  * §param  Request  $request 

13  * §return  Response 

14  */ 

15  public  function  store(Request  Srequest) 

16  { 

17  $name  = Srequest- > input( ' name ') ; 

18 

19  // 

20  } 

21  } 


If  your  controller  method  is  also  expecting  input  from  a route  parameter,  simply  list  your  route 
arguments  after  your  other  dependencies.  For  example,  if  your  route  is  defined  like  so: 
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1 Route :: put( ' user/{ id} ' , ' UserControl ler§update ') ; 


You  may  still  type-hint  the  Illuminate\Http\Request  and  access  your  route  parameter  id  by 
defining  your  controller  method  like  the  following: 


1 < ?php 

2 

3 namespace  App\Http\Control lers; 

4 

5 use  1 1 luminate\Http\Request; 

6 

7 class  UserControl ler  extends  Controller 

8 { 

9 /** 

10  * Update  the  specified  user. 

11  * 

12  * §param  Request  $request 

13  * @param  string  $id 

14  * §return  Response 

15  */ 

public  function  update(Request  $request,  $id) 

17  { 

18  // 

19  } 

20  } 


Basic  Request  Information 

The  1 1 luminate\Http\Request  instance  provides  a variety  of  methods  for  examining  the  HTTP 
request  for  your  application  and  extends  the  Symfony\Component\HttpFoundation\Request  class. 
Here  are  a few  more  of  the  useful  methods  available  on  this  class: 


Retrieving  The  Request  URI 

The  path  method  returns  the  request’s  URL  So,  if  the  incoming  request  is  targeted  at  http : //doma  i n . com/  f oo/bar, 
the  path  method  will  return  foo/bar: 
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1 

$uri  = $request->path( ) ; 

The  is  method  allows  you  to  verify  that  the  incoming  request  URI  matches  a given  pattern.  You 
may  use  the  * character  as  a wildcard  when  utilizing  this  method: 

l 

if  ($request- > is( ' admin/* ') ) { 

2 

// 

3 

} 

To  get  the  full  URL,  not  just  the  path  info,  you  may  use  the  url  or  ful  lllrl  methods 

on  the  request 

instance: 

l 

//  Without  Query  String... 

2 

$url  = $request->url( ); 

4 

//  With  Query  String. . . 

5 

$url  = $request->  ful  lllrl  () ; 

Retrieving  The  Request  Method 

The  method  method  will  return  the  HTTP  verb  for  the  request.  You  may  also  use 

the  isMethod 

method  to  verify  that  the  HTTP  verb  matches  a given  string: 

1 

$method  = Srequest- >method( ) ; 

3 

if  (Srequest- > isMethod( 1 post 1 ) ) { 

4 

// 

5 

} 

PSR-7  Requests 

The  PSR-7  standard  specifies  interfaces  for  HTTP  messages,  including  requests  and  responses.  If 
you  would  like  to  obtain  an  instance  of  a PSR-7  request,  you  will  first  need  to  install  a few  libraries. 
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Laravel  uses  the  Symfony  HTTP  Message  Bridge  component  to  convert  typical  Laravel  requests  and 
responses  into  PSR-7  compatible  implementations: 


1 composer  require  symfony/psr-http-message-bridge 

2 

3  composer  require  zendframework/zend-diactoros 


Once  you  have  installed  these  libraries,  you  may  obtain  a PSR-7  request  by  simply  type-hinting  the 
request  type  on  your  route  or  controller: 

1 use  Psr\Http\Message\ServerRequestInter face; 

2 

3 Route :: get( , function  (ServerRequestlnterface  $request)  { 

4 // 

5 }); 


If  you  return  a PSR-7  response  instance  from  a route  or  controller,  it  will  automatically  be  converted 
back  to  a Laravel  response  instance  and  be  displayed  by  the  framework. 

Retrieving  Input 

Retrieving  An  Input  Value 

Using  a few  simple  methods,  you  may  access  all  user  input  from  your  Illuminate\Http\Request 
instance.  You  do  not  need  to  worry  about  the  HTTP  verb  used  for  the  request,  as  input  is  accessed 
in  the  same  way  for  all  verbs: 


1 $name  = $request-> input( ' name *  1 ) ; 


You  may  pass  a default  value  as  the  second  argument  to  the  input  method.  This  value  will  be 
returned  if  the  requested  input  value  is  not  present  on  the  request: 

1 $name  = $request- > input( ' name ' , 'Sally'); 
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When  working  on  forms  with  array  inputs,  you  may  use  “dot”  notation  to  access  the  arrays: 


1 $name  = $request-> input( ' products . 0 . name ') ; 

2 

3 $names  = $request- > input( ' products . name  1 ) ; 


Determining  If  An  Input  Value  Is  Present 

To  determine  if  a value  is  present  on  the  request,  you  may  use  the  has  method.  The  has  method 
returns  true  if  the  value  is  present  and  is  not  an  empty  string: 


1 if  (Srequest- >has( ' name ') ) { 

2 // 

3 } 


Retrieving  All  Input  Data 

You  may  also  retrieve  all  of  the  input  data  as  an  array  using  the  all  method: 

1 Sinput  = Srequest- >al 1 ( ) ; 


Retrieving  A Portion  Of  The  Input  Data 

If  you  need  to  retrieve  a sub-set  of  the  input  data,  you  may  use  the  only  and  except  methods.  Both 
of  these  methods  will  accept  a single  array  or  a dynamic  list  of  arguments: 

1 Sinput  = Srequest- >only( [' username ' , 'password']); 

2 

3 Sinput  = Srequest- >only( 1 username ' , 'password'); 

4 

5 Sinput  = Srequest- >except( [' credit_card ']) ; 

6 

7 Sinput  = Srequest- >except( ' credit_card ') ; 
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Dynamic  Properties 

You  may  also  access  user  input  using  dynamic  properties  on  the  1 1 luminate\Http\Request  instance. 
For  example,  if  one  of  your  application’s  forms  contains  a name  field,  you  may  access  the  value  of 
the  posted  field  like  so: 

1 $name  = $request- >name; 


When  using  dynamic  properties,  Laravel  will  first  look  for  the  parameter’s  value  in  the  request 
payload  and  then  in  the  route  parameters. 

Old  Input 

Laravel  allows  you  to  keep  input  from  one  request  during  the  next  request.  This  feature  is  particularly 
useful  for  re-populating  forms  after  detecting  validation  errors.  However,  if  you  are  using  Laravel’s 
included  validation  services,  it  is  unlikely  you  will  need  to  manually  use  these  methods,  as  some  of 
Laravel’s  built-in  validation  facilities  will  call  them  automatically. 

Flashing  Input  To  The  Session 

The  flash  method  on  the  Illuminate\Http\Request  instance  will  flash  the  current  input  to  the 
session  so  that  it  is  available  during  the  user’s  next  request  to  the  application: 


1 $request-> f lash( ) ; 


You  may  also  use  the  flashOnly  and  flashExcept  methods  to  flash  a sub-set  of  the  request  data 
into  the  session: 


1 $request-> flashOnly( [' username  1 , 'email']); 

2 

3 $request->  f lashExcept( ' password ' ) ; 
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Flash  Input  Into  Session  Then  Redirect 

Since  you  often  will  want  to  flash  input  in  association  with  a redirect  to  the  previous  page,  you  may 
easily  chain  input  flashing  onto  a redirect  using  the  withlnput  method: 

1 return  redirect( ' form ' ) - >withlnput( ) ; 

2 

3 return  redirect( ' form ' ) - >withlnput($request- >except( 1 password  1 ) ) ; 


Retrieving  Old  Data 

To  retrieve  flashed  input  from  the  previous  request,  use  the  old  method  on  the  Request  instance. 
The  old  method  provides  a convenient  helper  for  pulling  the  flashed  input  data  out  of  the  session: 

1 $username  = $request- >old( ' username ') ; 


Laravel  also  provides  a global  old  helper  function.  If  you  are  displaying  old  input  within  a Blade 
template,  it  is  more  convenient  to  use  the  old  helper.  If  no  old  input  exists  for  the  given  string,  null 
will  be  returned: 


1 < input  type="text"  name="username"  value="/Y  old( ' username ' ) }}"> 


Cookies 

Retrieving  Cookies  From  The  Request 

All  cookies  created  by  the  Laravel  framework  are  encrypted  and  signed  with  an  authentication  code, 
meaning  they  will  be  considered  invalid  if  they  have  been  changed  by  the  client.  To  retrieve  a cookie 
value  from  the  request,  you  may  use  the  cookie  method  on  the  1 1 luminate\Http\Request  instance: 

1 lvalue  = Irequest- >cookie( ' name ' ) ; 
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Attaching  A New  Cookie  To  A Response 

Laravel  provides  a global  cookie  helper  function  which  serves  as  a simple  factory  for  generating 
new  Symfony\Component\HttpFoundation\Cookie  instances.  The  cookies  may  be  attached  to  a 
1 1 luminate\Http\Response  instance  using  the  withCookie  method: 


1 Sresponse  = new  1 1 luminate\Http\Response( 1 2 3 Hel lo  World'); 

2 

3 $response- >withCookie( ' name ' , 'value',  $minutes); 

4 

5 return  $response; 


To  create  a long-lived  cookie,  which  lasts  for  five  years,  you  may  use  the  forever  method  on  the 
cookie  factory  by  first  calling  the  cookie  helper  with  no  arguments,  and  then  chaining  the  forever 
method  onto  the  returned  cookie  factory: 


1 $response- >withCookie(cookie( )-> forever (' name ' , 'value')); 


Files 

Retrieving  Uploaded  Files 

You  may  access  uploaded  files  that  are  included  with  the  1 1 luminate\Http\Request  instance 
using  the  file  method.  The  object  returned  by  the  file  method  is  an  instance  of  the  Sym- 
fony\Component\HttpFoundation\File\UploadedFile  class,  which  extends  the  PHP  SplFilelnfo 
class  and  provides  a variety  of  methods  for  interacting  with  the  file: 

1 $file  = $request- > fi le( ' photo ') ; 


You  may  determine  if  a file  is  present  on  the  request  using  the  hasF i le  method: 


1 if  (Irequest- >hasFi le( ' photo ') ) { 

2 // 

3 } 
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Validating  Successful  Uploads 

In  addition  to  checking  if  the  file  is  present,  you  may  verify  that  there  were  no  problems  uploading 
the  file  via  the  isVal  id  method: 


1 if  (Irequest- > fi le( ' photo ')-> isVal id( ) ) { 

2 // 

3 } 


Moving  Uploaded  Files 

To  move  the  uploaded  file  to  a new  location,  you  should  use  the  move  method.  This  method  will 
move  the  file  from  its  temporary  upload  location  (as  determined  by  your  PHP  configuration)  to  a 
more  permanent  destination  of  your  choosing: 


1 Irequest- > f i le( ’ photo 1 ) - > move (Iciest i nation Path) ; 

2 

3 |request->file( 'photo' )->move(|destinationPath,  IfileName); 


Other  File  Methods 

There  are  a variety  of  other  methods  available  on  UploadedFile  instances.  Check  out  the  API 
documentation  for  the  class57  for  more  information  regarding  these  methods. 

57http://api.symfony.com/3.0/Symfony/Component/HttpFoundation/File/UploadedFile.html 
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• Basic  Responses  A>  - Attaching  Headers  To  Responses  A>  - Attaching  Cookies  To  Responses 
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Basic  Responses 

Of  course,  all  routes  and  controllers  should  return  some  kind  of  response  to  be  sent  back  to  the 
user’s  browser.  Laravel  provides  several  different  ways  to  return  responses.  The  most  basic  response 
is  simply  returning  a string  from  a route  or  controller: 

1 Route :: get( , function  ()  { 
return  'Hello  World'; 

3 }); 


The  given  string  will  automatically  be  converted  into  an  HTTP  response  by  the  framework. 

Response  Objects 

However,  for  most  routes  and  controller  actions,  you  will  be  returning  a full  1 1 1 uminate\Http\Response 
instance  or  a view.  Returning  a full  Response  instance  allows  you  to  customize  the  response’s  HTTP 
status  code  and  headers.  A Response  instance  inherits  from  the  Symfony\Component\HttpFoundation\Response 
class,  providing  a variety  of  methods  for  building  HTTP  responses: 


1 use  1 1 luminate\Http\Response; 

2 

3 Route :: get( ' home ' , function  ()  { 

return  (new  Response($content,  $status)) 

5 - >header( ' Content-Type ' , lvalue); 

6 }); 


For  convenience,  you  may  also  use  the  response  helper: 
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1 

2 

3 


Route :: get( ' home ' , function  ()  { 

return  response($content,  $status) 

- > header ( ' Content -Type  1 , lvalue) ; 


4 }); 


o 


Note:  For  a full  list  of  available  Response  methods,  check  out  its  API  documentation58  and 
the  Symfony  API  documentation59. 


Attaching  Headers  To  Responses 


Keep  in  mind  that  most  response  methods  are  chainable,  allowing  for  the  fluent  building  of 
responses.  For  example,  you  may  use  the  header  method  to  add  a series  of  headers  to  the  response 
before  sending  it  back  to  the  user: 


1 

return  response($content) 

2 

->header( 'Content-Type' 

$type) 

3 

->header( 'X-Header-One' 

' Header  Value ' ) 

4 

->header( 'X-Header-Two' 

' Header  Value ' ) ; 

Or,  you  may  use  the  withHeaders  method  to  specify  an  array  of  headers  to  be  added  to  the  response: 

1 return  response($content) 

- >withHeaders( [ 

'Content-Type'  =>  $type, 

4 ' X-Header-One ' =>  'Header  Value’, 

5 ’ X-Header-Two 1 =>  'Header  Value’, 


Attaching  Cookies  To  Responses 

The  cookie  helper  method  on  the  response  instance  allows  you  to  easily  attach  cookies  to  the 
response.  For  example,  you  may  use  the  cookie  method  to  generate  a cookie  and  attach  it  to  the 
response  instance: 

58http://laravel.com/api/master/Illuminate/Http/Response.html 

59http://api.symfony.com/3.0/Symfony/Component/HttpFoundation/Response.html 
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]); 
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1  return  response($content) 

->header( 'Content-Type' , $type) 
->cookie( ' name  1 , 'value'); 


The  cookie  method  accepts  additional  optional  arguments  which  allow  you  to  further  customize 
your  cookie’s  properties: 


1 ->cookie($name,  $value,  Iminutes,  $path,  $domain,  $secure,  $httpOnly) 


By  default,  all  cookies  generated  by  Laravel  are  encrypted  and  signed  so  that  they  can’t  be  modified 
or  read  by  the  client.  If  you  would  like  to  disable  encryption  for  a certain  subset  of  cookies  generated 
by  your  application,  you  may  use  the  $except  property  of  the  App  \Http  \M  i dd  1 eware  \Encr  y ptCook  i es 
middleware: 


1 /** 

2 * The  names  of  the  cookies  that  should  not  be  encrypted. 

3 * 

4 * @var  array 

5 V 

6 protected  Sexcept  = [ 

7 ' cookie_name ' , 

8 ]; 


Other  Response  Types 

The  response  helper  may  be  used  to  conveniently  generate  other  types  of  response  instances.  When 

the  response  helper  is  called  without  arguments,  an  implementation  of  the  Illuminate  \Contracts  \Rout  i ng  \Respor 

contract  is  returned.  This  contract  provides  several  helpful  methods  for  generating  responses. 

View  Responses 

If  you  need  control  over  the  response  status  and  headers,  but  also  need  to  return  a view  as  the 
response  content,  you  may  use  the  view  method: 
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1 return  response() 

- >view( ' hel lo ' , $data) 

->header( 'Content-Type' , $type); 


Of  course,  if  you  do  not  need  to  pass  a custom  HTTP  status  code  or  custom  headers,  you  should 
simply  use  the  global  view  helper  function. 

JSON  Responses 

The  json  method  will  automatically  set  the  Content-Type  header  to  appl  ication/json,  as  well  as 
convert  the  given  array  into  JSON  using  the  json_encode  PHP  function: 

1 return  response( ) - > json( [ ' name ' =>  'Abigail',  'state'  =>  'CA']); 


If  you  would  like  to  create  a JSONP  response,  you  may  use  the  json  method  in  addition  to 
setCal lback: 


1 return  response() 

- > json( [ ' name ' =>  'Abigail',  'state'  =>  'CA']) 
- >setCal lback($request- > input( 'callback'  )) ; 


File  Downloads 

The  down  1 oad  method  may  be  used  to  generate  a response  that  forces  the  user’s  browser  to  download 
the  file  at  the  given  path.  The  download  method  accepts  a file  name  as  the  second  argument  to  the 
method,  which  will  determine  the  file  name  that  is  seen  by  the  user  downloading  the  file.  Finally, 
you  may  pass  an  array  of  HTTP  headers  as  the  third  argument  to  the  method: 

1 return  response( ) - >download($pathToFi le) ; 

2 

3 return  response( )->download($pathToFile,  $name,  $headers); 


o 


Note:  Symfony  HttpFoundation,  which  manages  file  downloads,  requires  the  file  being 
downloaded  to  have  an  ASCII  file  name. 
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Redirects 

Redirect  responses  are  instances  of  the  1 1 luminate\Http\RedirectResponse  class,  and  contain  the 
proper  headers  needed  to  redirect  the  user  to  another  URL.  There  are  several  ways  to  generate  a 
RedirectResponse  instance.  The  simplest  method  is  to  use  the  global  redirect  helper  method: 

1 Route :: get( ' dashboard ' , function  ()  { 
return  redirect( ' home/dashboard ' ) ; 

3 }); 


Sometimes  you  may  wish  to  redirect  the  user  to  their  previous  location,  for  example,  after  a form 
submission  that  is  invalid.  You  may  do  so  by  using  the  global  back  helper  function.  However,  make 
sure  the  route  using  the  back  function  is  using  the  web  middleware  group  or  has  all  of  the  session 
middleware  applied: 

1 Route :: post( ' user/prof i le ' , function  ()  { 

//  Validate  the  request. . . 

3 

4 return  back( ) - >withlnput( ) ; 

5 }); 


Redirecting  To  Named  Routes 

When  you  call  the  red  i rect  helper  with  no  parameters,  an  instance  of  1 1 1 um i nate\Rout  i ng  \Red  i rector 
is  returned,  allowing  you  to  call  any  method  on  the  Red  i rector  instance.  For  example,  to  generate 
a RedirectResponse  to  a named  route,  you  may  use  the  route  method: 

1 return  redirect( ) ->route( ' login ') ; 


If  your  route  has  parameters,  you  may  pass  them  as  the  second  argument  to  the  route  method: 

1 //  For  a route  with  the  following  URI:  profile/{id} 

2 
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3 return  redirect( ) - >route( ' prof i le ' , [’id1  =>  1]); 


If  you  are  redirecting  to  a route  with  an  “ID”  parameter  that  is  being  populated  from  an  Eloquent 
model,  you  may  simply  pass  the  model  itself.  The  ID  will  be  extracted  automatically: 

1 return  redirect( ) - >route( 1 prof i le 1 , [$user]); 


Redirecting  To  Controller  Actions 

You  may  also  generate  redirects  to  controller  actions.  To  do  so,  simply  pass  the  controller  and 
action  name  to  the  action  method.  Remember,  you  do  not  need  to  specify  the  full  namespace  to 
the  controller  since  Laravel’s  RouteServiceProvider  will  automatically  set  the  default  controller 
namespace: 


1 return  redirect( ) - >action( ’ HomeControl ler@index 1 ) ; 


Of  course,  if  your  controller  route  requires  parameters,  you  may  pass  them  as  the  second  argument 
to  the  action  method: 

1 return  redirect( ) - >action( ' UserControl ler@prof i le 1 , ['id'  =>  1]); 


Redirecting  With  Flashed  Session  Data 

Redirecting  to  a new  URL  and  flashing  data  to  the  session  are  typically  done  at  the  same  time.  So, 
for  convenience,  you  may  create  a RedirectResponse  instance  and  flash  data  to  the  session  in  a 
single  method  chain.  This  is  particularly  convenient  for  storing  status  messages  after  an  action: 

1 Route :: post( ' user/profi le ' , function  ()  { 

//  Update  the  user's  profile... 

3 

4 return  redirect( ' dashboard ')- >with( ' status ' , 'Profile  updated!'); 
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5 }); 


Of  course,  after  the  user  is  redirected  to  a new  page,  you  may  retrieve  and  display  the  flashed  message 
from  the  session.  For  example,  using  Blade  syntax: 


1 @if  (session( ' status  1 ) ) 

<div  class="alert  alert-success" > 
{{  session( 1 status ' ) }} 

4 </div> 

5 @endif 


Response  Macros 

If  you  would  like  to  define  a custom  response  that  you  can  re-use  in  a variety  of  your  routes 
and  controllers,  you  may  use  the  macro  method  on  the  Response  facade  or  the  implementation 
of  II  luminate\Contracts\Routing\ResponseFactory. 

For  example,  from  a service  provider’s  boot  method: 

1 < ?php 

2 

3 namespace  App\Providers; 

4 

5 use  Response; 

6 use  Illuminate\Support\ServiceProvider; 

7 

8 class  ResponseMacroServiceProvider  extends  ServiceProvider 

9 { 

10  /** 

11  * Perform  post-registration  booting  of  services. 

12  * 

13  * § return  void 

14  */ 

15  public  function  boot() 

16  { 

17  Response :: macro( ' caps ' , function  ($value)  { 

18  return  Response :: make(strtoupper($value) ) ; 

19  }); 
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20  } 
21  } 


The  macro  function  accepts  a name  as  its  first  argument,  and  a Closure  as  its  second.  The  macro’s 
Closure  will  be  executed  when  calling  the  macro  name  from  a ResponseFactory  implementation  or 
the  response  helper: 

1 return  response( ) ->caps( ' foo 1 ) ; 


Views 


• Basic  Usage  A>  - Passing  Data  To  Views  A>  - Sharing  Data  With  All  Views 

• View  Composers 

Basic  Usage 

Views  contain  the  HTML  served  by  your  application  and  separate  your  controller  / application  logic 
from  your  presentation  logic.  Views  are  stored  in  the  resources/views  directory 

A simple  view  might  look  something  like  this: 


1 <!--  View  stored  in  resources/views/greeting . php  --> 

2 

3 <html> 

4 <body> 

5 <hl>Hello,  <?php  echo  $name;  ?></hl> 

6 </body> 

7 </html> 


Since  this  view  is  stored  at  resources/views/greeting  . php,  we  may  return  it  using  the  global  view 
helper  function  like  so: 


1 Route :: get( , function  ()  { 

return  view( ' greeting ' , ['name'  =>  'James']); 

3 }); 


As  you  can  see,  the  first  argument  passed  to  the  view  helper  corresponds  to  the  name  of  the  view 
file  in  the  resources/views  directory.  The  second  argument  passed  to  helper  is  an  array  of  data 
that  should  be  made  available  to  the  view.  In  this  case,  we  are  passing  the  name  variable,  which  is 
displayed  in  the  view  by  executing  echo  on  the  variable. 

Of  course,  views  may  also  be  nested  within  sub-directories  of  the  resources/views  directory. 
“Dot”  notation  may  be  used  to  reference  nested  views.  For  example,  if  your  view  is  stored  at 
resources/views/admin/profile. php,  you  may  reference  it  like  so: 
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1  return  view( ' admin . prof i le ' , $data); 


Determining  If  A View  Exists 

If  you  need  to  determine  if  a view  exists,  you  may  use  the  exists  method  after  calling  the  view 
helper  with  no  arguments.  This  method  will  return  true  if  the  view  exists  on  disk: 


1 if  (view( )- >exists( 1 emai Is . customer ') ) { 

2 // 

3 } 


When  the  view  helper  is  called  without  arguments,  an  instance  of  1 1 luminate\Contracts\View\Factory 
is  returned,  giving  you  access  to  any  of  the  factory’s  methods. 

View  Data 

Passing  Data  To  Views 

As  you  saw  in  the  previous  examples,  you  may  easily  pass  an  array  of  data  to  views: 

1 return  view( ' greetings ' , ['name'  =>  'Victoria']); 


When  passing  information  in  this  manner,  $data  should  be  an  array  with  key/value  pairs.  Inside 
your  view,  you  can  then  access  each  value  using  its  corresponding  key,  such  as  <?php  echo  $key; 
?>.  As  an  alternative  to  passing  a complete  array  of  data  to  the  view  helper  function,  you  may  use 
the  with  method  to  add  individual  pieces  of  data  to  the  view: 

1 return  view( 1 greeting ')- >with( 1 name ' , ’Victoria'); 


Sharing  Data  With  All  Views 

Occasionally,  you  may  need  to  share  a piece  of  data  with  all  views  that  are  rendered  by  your  appli- 
cation. You  may  do  so  using  the  view  factory’s  share  method.  Typically,  you  should  place  calls  to 
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share  within  a service  provider’s  boot  method.  You  are  free  to  add  them  to  the  AppServiceProvider 
or  generate  a separate  service  provider  to  house  them: 


1 < ?php 

2 

3 namespace  App\Providers; 

4 

5 class  AppServiceProvider  extends  ServiceProvider 

6 { 

7 /** 

* Bootstrap  any  application  services. 

g * 

10  * §return  void 

11  */ 

12  public  function  boot() 

13  { 

view( ) - >share( ' key ' , 'value'); 

15  } 

16 

17  /** 

18  * Register  the  service  provider. 

19  * 

20  * @return  void 

21  */ 

public  function  registerQ 

23  { 

24  // 

25  } 

26  } 


View  Composers 

View  composers  are  callbacks  or  class  methods  that  are  called  when  a view  is  rendered.  If  you  have 
data  that  you  want  to  be  bound  to  a view  each  time  that  view  is  rendered,  a view  composer  can  help 
you  organize  that  logic  into  a single  location. 

Let’s  register  our  view  composers  within  a service  provider.  We’ll  use  the  view  helper  to  access 
the  underlying  1 1 luminate\Contracts\View\Factory  contract  implementation.  Remember,  Laravel 
does  not  include  a default  directory  for  view  composers.  You  are  free  to  organize  them  however  you 
wish.  For  example,  you  could  create  an  App\Http\ViewComposers  directory: 
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1 < ?php 

2 

3 namespace  App\Providers; 

4 

5 use  1 1 luminate\Support\ServiceProvider ; 

6 

7 class  ComposerServiceProvider  extends  ServiceProvider 

8 { 

g /** 

10  * Register  bindings  in  the  container . 

11  * 

12  * §return  void 

13  */ 

14  public  function  boot() 

15  { 

16  //  Using  class  based  composers . . . 

17  view( ) - >composer( 

18  'profile' , ' App\Http\ViewComposers\Prof i leComposer ' 

19  ); 

20 

21  //  Using  Closure  based  composers . . . 

view( )- >composer( ' dashboard ' , function  ($view)  { 

23  // 

24  }); 

25  } 

26 

27  /** 

28  * Register  the  service  provider. 

29  * 

30  * §return  void 

31  */ 

32  public  function  registerQ 

33  { 

34  // 

35  } 

36  } 


Remember,  if  you  create  a new  service  provider  to  contain  your  view  composer  registrations,  you 
will  need  to  add  the  service  provider  to  the  providers  array  in  the  conf  ig/app . php  configuration 
file. 

Now  that  we  have  registered  the  composer,  the  Prof  i leComposer@compose  method  will  be  executed 
each  time  the  profile  view  is  being  rendered.  So,  let’s  define  the  composer  class: 
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1 < ?php 

2 

3 namespace  App\Http\ViewComposers; 

4 

5 use  1 1 luminate\View\View; 

6 use  1 1 luminate\Users\Repository  as  UserRepository ; 

7 

8 class  Prof i leComposer 

9 { 

10  /** 

11  * The  user  repository  implementation . 

12  * 

13  * §var  UserRepository 

14  */ 

15  protected  $users; 

16 

17 

18  * Create  a new  profile  composer. 

19  * 

20  * §param  UserRepository  $users 

21  * §return  void 

22  */ 

public  function  construct( UserRepository  $users) 

24  { 

25  //  Dependencies  automatical ly  resolved  by  service  container . . . 

26  $this->users  = $users; 

27  } 

28 

29  /** 

30  * Bind  data  to  the  view. 

31  * 

32  * §param  View  $view 

33  * §return  void 

34  */ 

35  public  function  compose(View  $view) 

36  { 

$view- >with( 1 count ' , $th is  - > users- > count ( ) ) ; 

38  } 

39  } 


Just  before  the  view  is  rendered,  the  composer’s  compose  method  is  called  with  the  Illumi- 
nate\View\View  instance.  You  may  use  the  with  method  to  bind  data  to  the  view. 
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o 


Note:  All  view  composers  are  resolved  via  the  service  container,  so  you  may  type-hint  any 
dependencies  you  need  within  a composer’s  constructor. 


Attaching  A Composer  To  Multiple  Views 

You  may  attach  a view  composer  to  multiple  views  at  once  by  passing  an  array  of  views  as  the  first 
argument  to  the  composer  method: 

1  view( ) - >composer ( 


The  composer  method  accepts  the  * character  as  a wildcard,  allowing  you  to  attach  a composer  to 
all  views: 

1 view( ) - >composer ( ' * ' , function  ($view)  { 

2 // 

3 }); 


View  Creators 

View  creators  are  very  similar  to  view  composers;  however,  they  are  fired  immediately  when  the 
view  is  instantiated  instead  of  waiting  until  the  view  is  about  to  render.  To  register  a view  creator, 
use  the  creator  method: 

1 view( ) - >creator ( ' profile' , ’ App\Http\ViewCreators\Prof i leCreator ’ ) ; 


['profile',  ’dashboard’], 

1 App \H tt p \V i ewComposer s \My V i ewComposer 

4 ); 
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Introduction 

Blade  is  the  simple,  yet  powerful  templating  engine  provided  with  Laravel.  Unlike  other  popular 
PHP  templating  engines,  Blade  does  not  restrict  you  from  using  plain  PHP  code  in  your  views.  All 
Blade  views  are  compiled  into  plain  PHP  code  and  cached  until  they  are  modified,  meaning  Blade 
adds  essentially  zero  overhead  to  your  application.  Blade  view  files  use  the  . blade . php  file  extension 
and  are  typically  stored  in  the  resources/views  directory. 

Template  Inheritance 

Defining  A Layout 

Two  of  the  primary  benefits  of  using  Blade  are  template  inheritance  and  sections.  To  get  started, 
let’s  take  a look  at  a simple  example.  First,  we  will  examine  a “master”  page  layout.  Since  most  web 
applications  maintain  the  same  general  layout  across  various  pages,  it’s  convenient  to  define  this 
layout  as  a single  Blade  view: 


1 <!--  Stored  in  resources/views/ layouts/master . blade . php  --> 

2 

3 <html> 

4 <head> 

5 <title>App  Name  - §yield( ' title ') </title> 

6 </head> 

7 <body> 

@section( 'sidebar' ) 

9 This  is  the  master  sidebar. 

10  §show 
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11 

12  <div  class="container"> 

13  @yield( ' content ' ) 

14  </div> 

15  </body> 

16  </html> 


As  you  can  see,  this  file  contains  typical  HTML  mark-up.  However,  take  note  of  the  §section  and 
@yield  directives.  The  §section  directive,  as  the  name  implies,  defines  a section  of  content,  while 
the  §y  i e 1 d directive  is  used  to  display  the  contents  of  a given  section. 

Now  that  we  have  defined  a layout  for  our  application,  let’s  define  a child  page  that  inherits  the 
layout. 


Extending  A Layout 

When  defining  a child  page,  you  may  use  the  Blade  @extends  directive  to  specify  which  layout 
the  child  page  should  “inherit”.  Views  which  @extends  a Blade  layout  may  inject  content  into  the 
layout’s  sections  using  @section  directives.  Remember,  as  seen  in  the  example  above,  the  contents 
of  these  sections  will  be  displayed  in  the  layout  using  §yield: 

1 <!--  Stored  in  resources/views/chi Id . blade . php  --> 

2 

3 @extends( ' layouts . master ' ) 

4 

5 @section( ' title ' , 'Page  Title') 

6 

7 §section( ' sidebar ' ) 

@@parent 

9 


10 

<p>This  is  appended  to  the 

master  sidebar. </p> 

11 

§endsection 

12 

13 

@section( 'content' ) 

14 

<p>This  is  my  body  content. 

</p> 

15 

@endsection 

In  this  example,  the  sidebar  section  is  utilizing  the  §§parent  directive  to  append  (rather  than 
overwriting)  content  to  the  layout’s  sidebar.  The  §@parent  directive  will  be  replaced  by  the  content 
of  the  layout  when  the  view  is  rendered. 
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Of  course,  just  like  plain  PHP  views,  Blade  views  may  be  returned  from  routes  using  the  global  view 
helper  function: 


1 Route :: get( ' blade  1 , function  ()  { 
return  view( ' chi  Id ' ) ; 

3 }); 


Displaying  Data 

You  may  display  data  passed  to  your  Blade  views  by  wrapping  the  variable  in  “curly”  braces.  For 
example,  given  the  following  route: 


1 Route :: get( ' greeting ' , function  ()  { 

return  view( ' welcome ' , ['name'  =>  'Samantha']); 

3 }); 


You  may  display  the  contents  of  the  name  variable  like  so: 

1 Hello,  {{  $name  }}. 


Of  course,  you  are  not  limited  to  displaying  the  contents  of  the  variables  passed  to  the  view.  You 
may  also  echo  the  results  of  any  PHP  function.  In  fact,  you  can  put  any  PHP  code  you  wish  inside 
of  a Blade  echo  statement: 


1 The  current  UNIX  timestamp  is  {{  time()  }}. 


Note:  Blade  { { } } statements  are  automatically  sent  through  PHP’s  htmlentities  function 
to  prevent  XSS  attacks. 
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Blade  & JavaScript  Frameworks 

Since  many  JavaScript  frameworks  also  use  “curly”  braces  to  indicate  a given  expression  should 
be  displayed  in  the  browser,  you  may  use  the  § symbol  to  inform  the  Blade  rendering  engine  an 
expression  should  remain  untouched.  For  example: 


1 <hl>Laravel </hl> 

2 

3 Hello,  §{{  name  }}. 


In  this  example,  the  @ symbol  will  be  removed  by  Blade;  however,  { { name  } } expression  will  remain 
untouched  by  the  Blade  engine,  allowing  it  to  instead  be  rendered  by  your  JavaScript  framework. 

Echoing  Data  If  It  Exists 

Sometimes  you  may  wish  to  echo  a variable,  but  you  aren’t  sure  if  the  variable  has  been  set.  We  can 
express  this  in  verbose  PHP  code  like  so: 

1 {{  isset($name)  ? $name  : 'Default'  }} 


However,  instead  of  writing  a ternary  statement,  Blade  provides  you  with  the  following  convenient 
short-cut: 

1 {{  $name  or  'Default'  }} 


In  this  example,  if  the  $name  variable  exists,  its  value  will  be  displayed.  However,  if  it  does  not  exist, 
the  word  Default  will  be  displayed. 

Displaying  Unescaped  Data 

By  default,  Blade  { { } } statements  are  automatically  sent  through  PHP’s  htmlentities  function  to 
prevent  XSS  attacks.  If  you  do  not  want  your  data  to  be  escaped,  you  may  use  the  following  syntax: 

1 Hello,  { ! ! $name  ! ! } . 
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Note:  Be  very  careful  when  echoing  content  that  is  supplied  by  users  of  your  application. 
Always  use  the  double  curly  brace  syntax  to  escape  any  HTML  entities  in  the  content. 


Control  Structures 


In  addition  to  template  inheritance  and  displaying  data,  Blade  also  provides  convenient  short-cuts  for 
common  PHP  control  structures,  such  as  conditional  statements  and  loops.  These  short-cuts  provide 
a very  clean,  terse  way  of  working  with  PHP  control  structures,  while  also  remaining  familiar  to 
their  PHP  counterparts. 

If  Statements 

You  may  construct  if  statements  using  the  §if,  @elseif,  @else,  and  §endif  directives.  These 
directives  function  identically  to  their  PHP  counterparts: 


1 @if  (count($records)  ===  1) 

I have  one  record ! 

3 @elseif  (count($records)  > 1) 
I have  multiple  records! 

5 §else 

I don't  have  any  records! 
7 @endif 


For  convenience,  Blade  also  provides  an  §unless  directive: 

1 @unless  (Auth : : check( ) ) 

You  are  not  signed  in. 

3 @endunless 


Loops 


In  addition  to  conditional  statements,  Blade  provides  simple  directives  for  working  with  PHP’s 
supported  loop  structures.  Again,  each  of  these  directives  functions  identically  to  their  PHP 
counterparts: 
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1 @for  ($i  = 0;  $i  < 10;  $i++) 

The  current  value  is  {{  $i  }} 

3 @endfor 

4 

5 §foreach  ($users  as  Suser) 

<p>This  is  user  {{  $user->id  }}</p> 

7 @endforeach 

8 

9  §forelse  ($users  as  Suser) 

10  <li>{{  $user->name  } } < / 1 i > 

11  @empty 

12  <p>No  users</p> 

13  @endforelse 

14 

15  @while  (true) 

<p>I'm  looping  forever. </p> 

17  @endwhile 


Including  Sub-Views 

Blade’s  ©include  directive,  allows  you  to  easily  include  a Blade  view  from  within  an  existing  view. 
All  variables  that  are  available  to  the  parent  view  will  be  made  available  to  the  included  view: 

l <div> 

@include( ' shared . errors ' ) 

3 

4 <form> 

5 <!--  Form  Contents  --> 

6 </form> 

7 </div> 


Even  though  the  included  view  will  inherit  all  data  available  in  the  parent  view,  you  may  also  pass 
an  array  of  extra  data  to  the  included  view: 


1 @include( 1 view . name ' , ['some'  =>  ’data']) 
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Note:  You  should  avoid  using  the DIR and FILE constants  in  your  Blade  views, 

since  they  will  refer  to  the  location  of  the  cached  view. 


Rendering  Views  For  Collections 

You  may  combine  loops  and  includes  into  one  line  with  Blade’s  ©each  directive: 
1 @each( ' view . name ' , $jobs,  'job') 


The  first  argument  is  the  view  partial  to  render  for  each  element  in  the  array  or  collection.  The 
second  argument  is  the  array  or  collection  you  wish  to  iterate  over,  while  the  third  argument  is 
the  variable  name  that  will  be  assigned  to  the  current  iteration  within  the  view.  So,  for  example,  if 
you  are  iterating  over  an  array  of  jobs,  typically  you  will  want  to  access  each  job  as  a job  variable 
within  your  view  partial. 

You  may  also  pass  a fourth  argument  to  the  @each  directive.  This  argument  determines  the  view 
that  will  be  rendered  if  the  given  array  is  empty. 


1 @each( ' view . name ' , $jobs,  'job',  ' view . empty ' ) 


Comments 

Blade  also  allows  you  to  define  comments  in  your  views.  However,  unlike  HTML  comments,  Blade 
comments  are  not  included  in  the  HTML  returned  by  your  application: 

1 {{--  This  comment  will  not  be  present  in  the  rendered  HTML  --}} 


Stacks 

Blade  also  allows  you  to  push  to  named  stacks  which  can  be  rendered  somewhere  else  in  another 
view  or  layout: 
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1  @push( ' scripts ' ) 

<script  src=" /example . js" > </script> 
3 @endpush 


You  may  push  to  the  same  stack  as  many  times  as  needed.  To  render  a stack,  use  the  ©stack  syntax: 

1 <head> 

2 <!--  Head  Contents  --> 

3 

4 @stack ( ' scr i pts ' ) 

5 </head> 


Service  Injection 

The  ©inject  directive  may  be  used  to  retrieve  a service  from  the  Laravel  service  container.  The  first 
argument  passed  to  ©inject  is  the  name  of  the  variable  the  service  will  be  placed  into,  while  the 
second  argument  is  the  class  / interface  name  of  the  service  you  wish  to  resolve: 


1 @inject( 1 metrics ' , ' App\Services\Metr icsService ' ) 

2 

3  <div> 

Monthly  Revenue:  {{  $metr ics- >monthlyRevenue( ) }}. 
5 </div> 


Extending  Blade 

Blade  even  allows  you  to  define  your  own  custom  directives.  You  can  use  the  directive  method  to 
register  a directive.  When  the  Blade  compiler  encounters  the  directive,  it  calls  the  provided  callback 
with  its  parameter. 

The  following  example  creates  a ©datetime($var ) directive  which  formats  a given  $var: 
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1 

<?php 

2 

3 

namespace  App\Providers; 

4 

5 

use  Blade; 

6 

use  I 1 luminate\Support\ServiceProvider ; 

7 

8 

class  AppServiceProvider  extends  ServiceProvider 

9 

{ 

10 

/** 

11 

* Perform  post-registration  booting  of  services. 

12 

* 

13 

* §return  void 

14 

*/ 

15 

public  function  boot() 

16 

{ 

17 

Blade :: directive( ' datetime ' , function($expression)  { 

18 

return  "<?php  echo  with{$expression} -> format( 'm/d/Y  H : i ' ) 

; ?>"; 

19 

}); 

20 

1 

21 

22 

23 

* Register  bindings  in  the  container . 

24 

* 

25 

* §return  void 

26 

*/ 

27 

public  function  registerQ 

28 

{ 

29 

// 

30 

1 

31 

1 

As  you  can  see,  Laravel’s  with  helper  function  was  used  in  this  directive.  The  with  helper  simply 
returns  the  object  / value  it  is  given,  allowing  for  convenient  method  chaining.  The  final  PHP 
generated  by  this  directive  will  be: 

1 <?php  echo  with($var)->format( 'm/d/Y  H : i ' ) ; ?> 
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Introduction 

When  using  any  tool  in  the  “real  world”,  you  feel  more  confident  if  you  understand  how  that  tool 
works.  Application  development  is  no  different.  When  you  understand  how  your  development  tools 
function,  you  feel  more  comfortable  and  confident  using  them. 

The  goal  of  this  document  is  to  give  you  a good,  high-level  overview  of  how  the  Laravel  framework 
“works”.  By  getting  to  know  the  overall  framework  better,  everything  feels  less  “magical”  and  you 
will  be  more  confident  building  your  applications. 

If  you  don’t  understand  all  of  the  terms  right  away,  don’t  lose  heart!  Just  try  to  get  a basic  grasp  of 
what  is  going  on,  and  your  knowledge  will  grow  as  you  explore  other  sections  of  the  documentation. 

Lifecycle  Overview 

First  Things 

The  entry  point  for  all  requests  to  a Laravel  application  is  the  pub  1 ic/ index,  php  file.  All  requests  are 
directed  to  this  file  by  your  web  server  (Apache  / Nginx)  configuration.  The  index . php  file  doesn’t 
contain  much  code.  Rather,  it  is  simply  a starting  point  for  loading  the  rest  of  the  framework. 

The  index. php  file  loads  the  Composer  generated  autoloader  definition,  and  then  retrieves  an 
instance  of  the  Laravel  application  from  bootstrap/app . php  script.  The  first  action  taken  by  Laravel 
itself  is  to  create  an  instance  of  the  application  / service  container. 


HTTP  / Console  Kernels 

Next,  the  incoming  request  is  sent  to  either  the  HTTP  kernel  or  the  console  kernel,  depending  on 
the  type  of  request  that  is  entering  the  application.  These  two  kernels  serve  as  the  central  location 
that  all  requests  flow  through.  For  now,  let’s  just  focus  on  the  HTTP  kernel,  which  is  located  in 
app/Http/Kernel . php. 
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The  HTTP  kernel  extends  the  1 1 luminate\Foundation\Http\Kernel  class,  which  defines  an  array 
of  bootstrappers  that  will  be  run  before  the  request  is  executed.  These  bootstrappers  configure 
error  handling,  configure  logging,  detect  the  application  environment,  and  perform  other  tasks  that 
need  to  be  done  before  the  request  is  actually  handled. 

The  HTTP  kernel  also  defines  a list  of  HTTP  middleware  that  all  requests  must  pass  through  before 
being  handled  by  the  application.  These  middleware  handle  reading  and  writing  the  HTTP  session, 
determine  if  the  application  is  in  maintenance  mode,  verifying  the  CSRF  token,  and  more. 

The  method  signature  for  the  HTTP  kernel’s  handle  method  is  quite  simple:  receive  a Request 
and  return  a Response.  Think  of  the  Kernel  as  being  a big  black  box  that  represents  your  entire 
application.  Feed  it  HTTP  requests  and  it  will  return  HTTP  responses. 

Service  Providers 

One  of  the  most  important  Kernel  bootstrapping  actions  is  loading  the  service  providers  for  your 
application.  All  of  the  service  providers  for  the  application  are  configured  in  the  conf  ig/app . php 
configuration  file’s  providers  array.  First,  the  register  method  will  be  called  on  all  providers,  then, 
once  all  providers  have  been  registered,  the  boot  method  will  be  called. 

Service  providers  are  responsible  for  bootstrapping  all  of  the  framework’s  various  components,  such 
as  the  database,  queue,  validation,  and  routing  components.  Since  they  bootstrap  and  configure 
every  feature  offered  by  the  framework,  service  providers  are  the  most  important  aspect  of  the 
entire  Laravel  bootstrap  process. 

Dispatch  Request 

Once  the  application  has  been  bootstrapped  and  all  service  providers  have  been  registered,  the 
Request  will  be  handed  off  to  the  router  for  dispatching.  The  router  will  dispatch  the  request  to 
a route  or  controller,  as  well  as  run  any  route  specific  middleware. 


Focus  On  Service  Providers 

Service  providers  are  truly  the  key  to  bootstrapping  a Laravel  application.  The  application  instance 
is  created,  the  service  providers  are  registered,  and  the  request  is  handed  to  the  bootstrapped 
application.  It’s  really  that  simple! 

Having  a firm  grasp  of  how  a Laravel  application  is  built  and  bootstrapped  via  service  providers  is 
very  valuable.  Of  course,  your  application’s  default  service  providers  are  stored  in  theapp/Providers 
directory. 

By  default,  the  AppServiceProvider  is  fairly  empty.  This  provider  is  a great  place  to  add  your 
application’s  own  bootstrapping  and  service  container  bindings.  Of  course,  for  large  applications, 
you  may  wish  to  create  several  service  providers,  each  with  a more  granular  type  of  bootstrapping. 
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Introduction 

The  default  Laravel  application  structure  is  intended  to  provide  a great  starting  point  for  both 
large  and  small  applications.  Of  course,  you  are  free  to  organize  your  application  however  you  like. 
Laravel  imposes  almost  no  restrictions  on  where  any  given  class  is  located  - as  long  as  Composer 
can  autoload  the  class. 

The  Root  Directory 

The  root  directory  of  a fresh  Laravel  installation  contains  a variety  of  folders: 

The  app  directory,  as  you  might  expect,  contains  the  core  code  of  your  application.  We’ll  explore 
this  folder  in  more  detail  soon. 

The  bootstrap  folder  contains  a few  files  that  bootstrap  the  framework  and  configure  autoloading, 
as  well  as  a cache  folder  that  contains  a few  framework  generated  files  for  bootstrap  performance 
optimization. 

The  con  fig  directory,  as  the  name  implies,  contains  all  of  your  application’s  configuration  files. 

The  database  folder  contains  your  database  migration  and  seeds.  If  you  wish,  you  may  also  use  this 
folder  to  hold  an  SQLite  database. 

The  public  directory  contains  the  front  controller  and  your  assets  (images,  JavaScript,  CSS,  etc.). 

The  resources  directory  contains  your  views,  raw  assets  (LESS,  SASS,  CoffeeScript),  and  localiza- 
tion files. 

The  storage  directory  contains  compiled  Blade  templates,  file  based  sessions,  file  caches,  and  other 
files  generated  by  the  framework.  This  folder  is  segregated  into  app,  framework,  and  logs  directories. 
The  app  directory  may  be  used  to  store  any  files  utilized  by  your  application.  The  framework 
directory  is  used  to  store  framework  generated  files  and  caches.  Finally,  the  logs  directory  contains 
your  application’s  log  files. 
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The  tests  directory  contains  your  automated  tests.  An  example  PHPUnit60  is  provided  out  of  the 
box. 

The  vendor  directory  contains  your  Composer61  dependencies. 


The  App  Directory 

The  “meat”  of  your  application  lives  in  the  app  directory.  By  default,  this  directory  is  namespaced 
under  App  and  is  autoloaded  by  Composer  using  the  PSR-4  autoloading  standard62. 

The  app  directory  ships  with  a variety  of  additional  directories  such  as  Conso  1 e,  Http,  and  Prov  i ders . 
Think  of  the  Console  and  Http  directories  as  providing  an  API  into  the  “core”  of  your  application. 
The  HTTP  protocol  and  CLI  are  both  mechanisms  to  interact  with  your  application,  but  do  not 
actually  contain  application  logic.  In  other  words,  they  are  simply  two  ways  of  issuing  commands 
to  your  application.  The  Console  directory  contains  all  of  your  Artisan  commands,  while  the  Http 
directory  contains  your  controllers,  middleware,  and  requests. 

The  Events  directory,  as  you  might  expect,  houses  event  classes.  Events  may  be  used  to  alert  other 
parts  of  your  application  that  a given  action  has  occurred,  providing  a great  deal  of  flexibility  and 
decoupling. 

The  Exceptions  directory  contains  your  application’s  exception  handler  and  is  also  a good  place  to 
stick  any  exceptions  thrown  by  your  application. 

The  Jobs  directory,  of  course,  houses  the  queueable  jobs  for  your  application.  Jobs  may  be  queued 
by  your  application  or  run  synchronously  within  the  current  request  lifecycle. 

The  Listeners  directory  contains  the  handler  classes  for  your  events.  Handlers  receive  an  event  and 
perform  logic  in  response  to  the  event  being  fired.  For  example,  a UserRegistered  event  might  be 
handled  by  a SendWelcomeEmail  listener. 

The  Policies  directory  contains  the  authorization  policy  classes  for  your  application.  Policies  are 
used  to  determine  if  a user  can  perform  a given  action  against  a resource.  For  more  information, 
check  out  the  authorization  documentation. 


Note:  Many  of  the  classes  in  the  app  directory  can  be  generated  by  Artisan  via  commands. 
To  review  the  available  commands,  run  the  php  artisan  list  make  command  in  your 
terminal. 


60https://phpunit.de/ 

61https://getcomposer.org 

62http://www.php-fig.org/psr/psr-4/ 
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Introduction 

Service  providers  are  the  central  place  of  all  Laravel  application  bootstrapping.  Your  own  application, 
as  well  as  all  of  Laravel’s  core  services  are  bootstrapped  via  service  providers. 

But,  what  do  we  mean  by  “bootstrapped”?  In  general,  we  mean  registering  things,  including  reg- 
istering service  container  bindings,  event  listeners,  middleware,  and  even  routes.  Service  providers 
are  the  central  place  to  configure  your  application. 

If  you  open  the  conf  ig/app . php  file  included  with  Laravel,  you  will  see  a providers  array.  These 
are  all  of  the  service  provider  classes  that  will  be  loaded  for  your  application.  Of  course,  many  of 
them  are  “deferred”  providers,  meaning  they  will  not  be  loaded  on  every  request,  but  only  when  the 
services  they  provide  are  actually  needed. 

In  this  overview  you  will  learn  how  to  write  your  own  service  providers  and  register  them  with 
your  Laravel  application. 

Writing  Service  Providers 

All  service  providers  extend  the  1 1 luminate\Support\ServiceProvider  class.  This  abstract  class 
requires  that  you  define  at  least  one  method  on  your  provider:  register.  Within  the  register 
method,  you  should  only  bind  things  into  the  service  container.  You  should  never  attempt  to 
register  any  event  listeners,  routes,  or  any  other  piece  of  functionality  within  the  register  method. 

The  Artisan  CLI  can  easily  generate  a new  provider  via  the  make : provider  command: 

1 php  artisan  make : provider  RiakServiceProvider 
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The  Register  Method 

As  mentioned  previously,  within  the  register  method,  you  should  only  bind  things  into  the  service 
container.  You  should  never  attempt  to  register  any  event  listeners,  routes,  or  any  other  piece  of 
functionality  within  the  register  method.  Otherwise,  you  may  accidently  use  a service  that  is 
provided  by  a service  provider  which  has  not  loaded  yet. 

Now,  let’s  take  a look  at  a basic  service  provider: 


1 < ?php 

2 

3 namespace  App\Providers; 

4 

5 use  Riak\Connection; 

6 use  1 1 luminate\Support\ServiceProvider ; 

7 

8 class  RiakServiceProvider  extends  ServiceProvider 

9 { 

10  /** 

11  * Register  bindings  in  the  container . 

12  * 

13  * §return  void 

14  */ 

15  public  function  register() 

16  { 

$this- >app->singleton(Connection :: class,  function  ($app)  { 
return  new  Connection(conf ig( 1 riak ' ) ) ; 

19  }); 

20  } 

21  } 


This  service  provider  only  defines  a register  method,  and  uses  that  method  to  define  an  imple- 
mentation of  Riak\Connection  in  the  service  container.  If  you  don’t  understand  how  the  service 
container  works,  check  out  its  documentation. 


The  Boot  Method 

So,  what  if  we  need  to  register  a view  composer  within  our  service  provider?  This  should  be 
done  within  the  boot  method.  This  method  is  called  after  all  other  service  providers  have 
been  registered,  meaning  you  have  access  to  all  other  services  that  have  been  registered  by  the 
framework: 
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1 < ?php 

2 

3 namespace  App\Providers; 

4 

5 use  1 1 luminate\Contracts\Events\Dispatcher  as  DispatcherContract; 

6 use  1 1 luminate\Foundation\Support\Providers\EventServiceProvider  as  ServiceProvi \ 

7 der ; 

8 

9  class  EventServiceProvider  extends  ServiceProvider 

10  { 

11  //  Other  Service  Provider  Properties . . . 

12 

13  /** 

14  * Register  any  other  events  for  your  application. 

15  * 

16  * §param  \Illuminate\Contracts\Events\Dispatcher  $events 

17  * §return  void 

18  */ 

19  public  function  boot( DispatcherContract  Sevents) 

20  { 

21  parent :: boot($events) ; 

22 

view( ) - >composer( ' view  1 , function  ()  { 

24  // 

25  }); 

26  } 

27  } 


Boot  Method  Dependency  Injection 

You  are  able  to  type-hint  dependencies  for  your  service  provider’s  boot  method.  The  service 
container  will  automatically  inject  any  dependencies  you  need: 
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1 use  1 1 luminate\Contracts\Routing\ResponseFactory ; 

2 

3 public  function  boot(ResponseFactory  $factory) 

4 { 

$factory- >macro( 1 caps ' , function  ($value)  { 

6 // 

7 }); 

8 } 


Registering  Providers 

All  service  providers  are  registered  in  the  conf  ig/app . php  configuration  file.  This  file  contains  a 
providers  array  where  you  can  list  the  names  of  your  service  providers.  By  default,  a set  of  Laravel 
core  service  providers  are  listed  in  this  array.  These  providers  bootstrap  the  core  Laravel  components, 
such  as  the  mailer,  queue,  cache,  and  others. 

To  register  your  provider,  simply  add  it  to  the  array: 


1 'providers'  =>  [ 

//  Other  Service  Providers 

3 

App\Providers\AppServiceProvider : : class, 

5 1, 


Deferred  Providers 

If  your  provider  is  only  registering  bindings  in  the  service  container,  you  may  choose  to  defer  its 
registration  until  one  of  the  registered  bindings  is  actually  needed.  Deferring  the  loading  of  such  a 
provider  will  improve  the  performance  of  your  application,  since  it  is  not  loaded  from  the  filesystem 
on  every  request. 

To  defer  the  loading  of  a provider,  set  the  defer  property  to  true  and  define  a provides  method. 
The  provides  method  returns  the  service  container  bindings  that  the  provider  registers: 
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1 < ?php 

2 

3 namespace  App\Providers; 

4 

5 use  Riak\Connection; 

6 use  1 1 luminate\Support\ServiceProvider ; 

7 

8 class  RiakServiceProvider  extends  ServiceProvider 

9 { 

10  /** 

11  * Indicates  if  loading  of  the  provider  is  deferred . 

12  * 

13  * §var  bool 

14  V 

15  protected  $defer  = true; 

16 

17 

18  * Register  the  service  provider. 

19  * 

20  * §return  void 

21  */ 

22  public  function  registerQ 

23  { 

24  $this- >app->singleton(Connection :: class,  function  ($app)  { 

25  return  new  Connection($app [ ' conf ig ' ] [ ' r iak ' ] ) ; 

26  }); 

27  } 

28 

29  /** 

* Get  the  services  provided  by  the  provider. 

31  * 

32  * §return  array 

33  */ 

34  public  function  provides() 

35  { 

36  return  [Connection  :class]; 

37  } 

38 

39  } 


Laravel  compiles  and  stores  a list  of  all  of  the  services  supplied  by  deferred  service  providers,  along 
with  the  name  of  its  service  provider  class.  Then,  only  when  you  attempt  to  resolve  one  of  these 
services  does  Laravel  load  the  service  provider. 
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The  Laravel  service  container  is  a powerful  tool  for  managing  class  dependencies  and  performing 
dependency  injection.  Dependency  injection  is  a fancy  phrase  that  essentially  means  this:  class 
dependencies  are  “injected”  into  the  class  via  the  constructor  or,  in  some  cases,  “setter”  methods. 

Let’s  look  at  a simple  example: 

1 < ?php 

2 

3 namespace  App\Jobs; 

4 

5 use  App\User; 

6 use  Illuminate\Contracts\Mail\Mailer; 

7 use  1 1 luminate\Contracts\Bus\Sel fHandl ing; 

8 

9 class  PurchasePodcast  implements  Sel fHandl ing 

10  { 


Introduction 
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* The  mailer  implementation . 

*/ 

protected  $mailer; 


12 

13 

14 

15 

16 


/** 

* Create  a new  instance. 

* 


17 

18 


19 

20 
21 
22 


* §param  Mailer  $mailer 

* @return  void 

*/ 

public  function  construct(Mai ler  $mailer) 


23 

24 


$this- >mai ler  = $mailer; 
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25  } 

26 

27  /** 

* Purchase  a podcast. 

29  * 

30  * §return  void 

31  */ 

public  function  handle() 

33  { 

34  // 

35  } 

36  } 


In  this  example,  the  PurchasePodcast  job  needs  to  send  e-mails  when  a podcast  is  purchased.  So,  we 
will  inject  a service  that  is  able  to  send  e-mails.  Since  the  service  is  injected,  we  are  able  to  easily 
swap  it  out  with  another  implementation.  We  are  also  able  to  easily  “mock”,  or  create  a dummy 
implementation  of  the  mailer  when  testing  our  application. 

A deep  understanding  of  the  Laravel  service  container  is  essential  to  building  a powerful,  large 
application,  as  well  as  for  contributing  to  the  Laravel  core  itself. 

Binding 

Almost  all  of  your  service  container  bindings  will  be  registered  within  service  providers,  so  all  of 
these  examples  will  demonstrate  using  the  container  in  that  context.  However,  there  is  no  need  to 
bind  classes  into  the  container  if  they  do  not  depend  on  any  interfaces.  The  container  does  not  need 
to  be  instructed  on  how  to  build  these  objects,  since  it  can  automatically  resolve  such  “concrete” 
objects  using  PHP’s  reflection  services. 

Within  a service  provider,  you  always  have  access  to  the  container  via  the  $this->app  instance 
variable.  We  can  register  a binding  using  the  bind  method,  passing  the  class  or  interface  name  that 
we  wish  to  register  along  with  a Closure  that  returns  an  instance  of  the  class: 

1 $this->app->bind( ' HelpSpot\API ' , function  ($app)  { 
return  new  HelpSpot\API ($app [ ' HttpCl ient ' ] ) ; 

3 }); 


Notice  that  we  receive  the  container  itself  as  an  argument  to  the  resolver.  We  can  then  use  the 
container  to  resolve  sub-dependencies  of  the  object  we  are  building. 
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Binding  A Singleton 

The  singleton  method  binds  a class  or  interface  into  the  container  that  should  only  be  resolved  one 
time,  and  then  that  same  instance  will  be  returned  on  subsequent  calls  into  the  container: 


1 $this- >app- >singleton( ' FooBar 1 , function  ($app)  { 
return  new  FooBar($app [ ' SomethingElse 1 ] ) ; 

3 }); 


Binding  Instances 

You  may  also  bind  an  existing  object  instance  into  the  container  using  the  instance  method.  The 
given  instance  will  always  be  returned  on  subsequent  calls  into  the  container: 


1 $fooBar  = new  FooBar(new  SomethingElse); 

2 

3 $this- >app- > instance( ' FooBar ' , $fooBar); 


Binding  Interfaces  To  Implementations 

A very  powerful  feature  of  the  service  container  is  its  ability  to  bind  an  interface  to  a given  imple- 
mentation. For  example,  let’s  assume  we  have  an  EventPusher  interface  and  a RedisEventPusher 
implementation.  Once  we  have  coded  our  RedisEventPusher  implementation  of  this  interface,  we 
can  register  it  with  the  service  container  like  so: 


1 $this- >app- >bind( ' App\Contracts\EventPusher ' , ' App\Services\RedisEventPusher ' ) ; 


This  tells  the  container  that  it  should  inject  the  RedisEventPusher  when  a class  needs  an  implemen- 
tation of  EventPusher.  Now  we  can  type-hint  the  EventPusher  interface  in  a constructor,  or  any 
other  location  where  dependencies  are  injected  by  the  service  container: 
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1 use  App\Contracts\EventPusher ; 

2 

3 /** 

4 * Create  a new  class  instance. 

5 * 

6 * @param  EventPusher  $pusher 

7 * @return  void 

8 */ 

9  public  function  construct( EventPusher  $pusher) 

10  { 

11  $this->pusher  = $pusher; 

12  } 


Contextual  Binding 

Sometimes  you  may  have  two  classes  that  utilize  the  same  interface,  but  you  wish  to  inject  different 
implementations  into  each  class.  For  example,  when  our  system  receives  a new  Order,  we  may  want 
to  send  an  event  via  PubNub63  rather  than  Pusher.  Laravel  provides  a simple,  fluent  interface  for 
defining  this  behavior: 


1 $this- >app- >when( ' App\Handlers\Commands\CreateOrderHandler ' ) 
- >needs( 1 App\Contracts\EventPusher ' ) 

->give( ' App\Services\PubNubEventPusher ' ); 


You  may  even  pass  a Closure  to  the  give  method: 

1 $this->app->when( ' App\Handlers\Commands\CreateOrderHandler ' ) 
- >needs( 1 App\Contracts\EventPusher 1 ) 

- >give( function  ()  { 

4 //  Resolve  dependency... 

5 }); 


63http://www.pubnub.com/ 
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Binding  Primitives 

Sometimes  you  may  have  a class  that  receives  some  injected  classes,  but  also  needs  an  injected 
primitive  value  such  as  an  integer.  You  may  easily  use  contextual  binding  to  inject  any  value  your 
class  may  need: 


1 $this- >app- >when( ' App\Handlers\Commands\CreateOrderHandler ' ) 
-> needs ( ' SmaxOrderCount ' ) 

->give(10); 


Tagging 

Occasionally,  you  may  need  to  resolve  all  of  a certain  “category”  of  binding.  For  example,  perhaps 
you  are  building  a report  aggregator  that  receives  an  array  of  many  different  Report  interface 
implementations.  After  registering  the  Report  implementations,  you  can  assign  them  a tag  using 
the  tag  method: 


1 

$this->app->bind( ' SpeedReport ' , 

function  ()  { 

2 

// 

3 

}); 

4 

5 

$this->app->bind( ' MemoryReport 1 

, function  ()  { 

6 

// 

7 

}); 

8 

9 

$this->app->tag( [ 'SpeedReport' , 

' MemoryReport ' ] , ' reports ' ) ; 

Once  the  services  have  been  tagged,  you  may  easily  resolve  them  all  via  the  tagged  method: 


1 $this->app->bind( ' ReportAggregator ' , function  ($app)  { 

return  new  ReportAggregator($app- >tagged( ' reports ')) ; 

3 }); 
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Resolving 


There  are  several  ways  to  resolve  something  out  of  the  container.  First,  you  may  use  the  make  method, 
which  accepts  the  name  of  the  class  or  interface  you  wish  to  resolve: 

1 $fooBar  = $this->app- >make( ' FooBar ') ; 


Secondly,  you  may  access  the  container  like  an  array,  since  it  implements  PHP’s  ArrayAccess 
interface: 


1 SfooBar  = $this- >app [' FooBar '] ; 


Lastly,  but  most  importantly,  you  may  simply  “type-hint”  the  dependency  in  the  constructor  of  a 
class  that  is  resolved  by  the  container,  including  controllers,  event  listeners,  queue  jobs,  middleware, 
and  more.  In  practice,  this  is  how  most  of  your  objects  are  resolved  by  the  container. 

The  container  will  automatically  inject  dependencies  for  the  classes  it  resolves.  For  example,  you 
may  type-hint  a repository  defined  by  your  application  in  a controller’s  constructor.  The  repository 
will  automatically  be  resolved  and  injected  into  the  class: 


1 < ?php 

2 

3 namespace  App\Http\Control lers; 

4 

5 use  App\Users\Repository  as  UserRepository ; 

6 

7 class  UserController  extends  Controller 


8 

9 


/** 

* The  user  repository  instance. 

*/ 

protected  $users; 


10 

11 

12 


13 

14 


/** 

* Create  a new  controller  instance. 

* 


15 

16 


19 


17 

18 


* §param  UserRepository  $ users 

* @return  void 
*/ 
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public  function  construct(UserRepository  $users) 

21  { 

22  $this->users  = Susers; 

23  } 

24 

25  /** 

26  * Show  the  user  with  the  given  ID. 

27  * 

28  * §param  int  $id 

29  * §return  Response 

30  */ 

31  public  function  show($id) 

32  { 

33  // 

34  } 

35  } 


Container  Events 

The  service  container  fires  an  event  each  time  it  resolves  an  object.  You  may  listen  to  this  event 
using  the  resolving  method: 

1 $this->app->resolving(function  ($object,  Sapp)  { 

//  Called  when  container  resolves  object  of  any  type... 

3 }); 

4 

5 $this->app->resolving(FooBar : :class,  function  (FooBar  SfooBar,  Sapp)  { 

6 //  Called  when  container  resolves  objects  of  type  "FooBar"... 

7 }); 


As  you  can  see,  the  object  being  resolved  will  be  passed  to  the  callback,  allowing  you  to  set  any 
additional  properties  on  the  object  before  it  is  given  to  its  consumer. 
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Introduction 

Laravel’s  Contracts  are  a set  of  interfaces  that  define  the  core  services  provided  by  the  framework. 
For  example,  a Illuminate\Contracts\Queue\Queue  contract  defines  the  methods  needed  for 
queueing  jobs,  while  the  1 1 luminate\Contracts\Mai  1 \Mai  ler  contract  defines  the  methods  needed 
for  sending  e-mail. 

Each  contract  has  a corresponding  implementation  provided  by  the  framework.  For  example,  Laravel 
provides  a queue  implementation  with  a variety  of  drivers,  and  a mailer  implementation  that  is 
powered  by  SwiftMailer64. 

All  of  the  Laravel  contracts  live  in  their  own  GitHub  repository65.  This  provides  a quick  reference 
point  for  all  available  contracts,  as  well  as  a single,  decoupled  package  that  may  be  utilized  by 
package  developers. 

Contracts  Vs.  Facades 

Laravel’s  facades  provide  a simple  way  of  utilizing  Laravel’s  services  without  needing  to  type-hint 
and  resolve  contracts  out  of  the  service  container.  However,  using  contracts  allows  you  to  define 
explicit  dependencies  for  your  classes.  For  most  applications,  using  a facade  is  just  fine.  However,  if 
you  really  need  the  extra  loose  coupling  that  contracts  can  provide,  keep  reading! 

Why  Contracts? 

You  may  have  several  questions  regarding  contracts.  Why  use  interfaces  at  all?  Isn’t  using  interfaces 
more  complicated?  Let’s  distil  the  reasons  for  using  interfaces  to  the  following  headings:  loose 
coupling  and  simplicity. 

64http://swiftmailer.org/ 

6 5 https  ://github  .com/illuminate/contracts 
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Loose  Coupling 

First,  let’s  review  some  code  that  is  tightly  coupled  to  a cache  implementation.  Consider  the 
following: 


1 < ?php 

2 

3 namespace  App\Orders; 

4 

5 class  Repository 

6 { 

7 /** 

8 * The  cache  instance. 

9 */ 

10  protected  $cache; 

11 

12  /** 

13  * Create  a new  repository  instance. 

14  * 

15  * §param  \SomePackage\Cache\Memcached  $cache 

16  * §return  void 

17  */ 

public  function  construct( \SomePackage\Cache\Memcached  $cache) 

19  { 

20  $this->cache  = $cache; 

21  } 

22 

23  /** 

24  * Retrieve  an  Order  by  ID. 

25  * 

26  * §param  int  $id 

27  * §return  Order 

28  */ 

29  public  function  find($id) 

30  { 

31  if  ($this->cache->has($id))  { 

32  // 

33  } 

34  } 

35  } 


In  this  class,  the  code  is  tightly  coupled  to  a given  cache  implementation.  It  is  tightly  coupled  because 
we  are  depending  on  a concrete  Cache  class  from  a package  vendor.  If  the  API  of  that  package 
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changes  our  code  must  change  as  well. 

Likewise,  if  we  want  to  replace  our  underlying  cache  technology  (Memcached)  with  another 
technology  (Redis),  we  again  will  have  to  modify  our  repository  Our  repository  should  not  have  so 
much  knowledge  regarding  who  is  providing  them  data  or  how  they  are  providing  it. 

Instead  of  this  approach,  we  can  improve  our  code  by  depending  on  a simple,  vendor  agnostic 
interface: 

1 < ?php 

2 

3 namespace  App\Orders; 

4 

5 use  1 1 luminate\Contracts\Cache\Repository  as  Cache; 

6 

7 class  Repository 

8 { 

9 /** 

10  * The  cache  instance. 

11  */ 

12  protected  $cache; 

13 

14  /** 

15  * Create  a new  repository  instance. 

16  * 

17  * @param  Cache  $cache 

18  * §return  void 

19  */ 

20  public  function  construct(Cache  $cache) 

21  { 

22  $this->cache  = $cache; 

23  } 

24  } 


Now  the  code  is  not  coupled  to  any  specific  vendor,  or  even  Laravel.  Since  the  contracts  package 
contains  no  implementation  and  no  dependencies,  you  may  easily  write  an  alternative  implementa- 
tion of  any  given  contract,  allowing  you  to  replace  your  cache  implementation  without  modifying 
any  of  your  cache  consuming  code. 

Simplicity 

When  all  of  Laravel’s  services  are  neatly  defined  within  simple  interfaces,  it  is  very  easy  to  determine 
the  functionality  offered  by  a given  service.  The  contracts  serve  as  succinct  documentation  to  the 
framework’s  features. 
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In  addition,  when  you  depend  on  simple  interfaces,  your  code  is  easier  to  understand  and  maintain. 
Rather  than  tracking  down  which  methods  are  available  to  you  within  a large,  complicated  class, 
you  can  refer  to  a simple,  clean  interface. 
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This  is  a reference  to  most  Laravel  Contracts,  as  well  as  their  Laravel  “facade”  counterparts: 

Contract  | References  Facade | IlluminateContractsAuthGuard66 1 Auth  Illuminate- 

ContractsAuthPasswordBroker67  | Password  IlluminateContractsBusDispatcher68  | Bus  Illuminate- 
ContractsBroadcastingBroadcaster69  | IlluminateContractsCacheRepository70  | Cache  Illuminate- 
ContractsCacheFactory71  | Cache::driver()  IlluminateContractsConfigRepository72  | Config  Illumi- 
nateContractsContainerContainer73 1 App  IlluminateContractsCookieFactory74 1 Cookie  Illuminate- 
ContractsCookieQueueingFactory75  | Cookie::queue()  IlluminateContractsEncryptionEncrypter76  | 
Crypt  IlluminateContractsEventsDispatcher77  | Event  IlluminateContractsFilesystemCloud78  | II- 
luminateContractsFilesystemFactory79  | File  IlluminateContractsFilesystemFilesystem80  | File  Illu- 
minateContractsFoundationApplication81 1 App  IlluminateContractsHashingHasher82 1 Hash  Illumi- 
nateContractsFoggingFog83  | Fog  IlluminateContractsMailMailQueue84  | Mail::queue()  Illuminate- 
ContractsMailMailer85  | Mail  IlluminateContractsQueueFactory86  | Queue:: dr iver()  IlluminateCon- 
tractsQueueQueue87  | Queue  IlluminateContractsRedisDatabase88  | Redis  IlluminateContractsRout- 
ingRegistrar89 1 Route  IlluminateContractsRoutingResponseFactory90 1 Response  IlluminateContract- 

66https://github.com/illuminate/contracts/blob/master/Auth/Guard.php 

6 7 https  ://github . com/illuminate/contracts/blob/master/ Auth/PasswordBroker  .php 

68https://github.com/illuminate/contracts/blob/master/Bus/Dispatcher.php 

69https://github.com/illuminate/contracts/blob/master/Broadcasting/Broadcaster.php 

70https://github.com/illuminate/contracts/blob/master/Cache/Repository.php 

71https://github.com/illuminate/contracts/blob/master/Cache/Factory.php 

72https://github.com/illuminate/contracts/blob/master/Config/Repository.php 

73https://github.com/illuminate/contracts/blob/master/Container/Container.php 

74https://github.com/illuminate/contracts/blob/master/Cookie/Factory.php 

75https://github.com/illuminate/contracts/blob/master/Cookie/QueueingFactory.php 

76https://github.com/illuminate/contracts/blob/master/Encryption/Encrypter.php 

77https://github.com/illuminate/contracts/blob/master/Events/Dispatcher.php 

78https://github.com/illuminate/contracts/blob/master/Filesystem/Cloud.php 

79https://github.com/illuminate/contracts/blob/master/Filesystem/Factory.php 

80https://github.com/illuminate/contracts/blob/master/Filesystem/Filesystem.php 

81https://github.com/illuminate/contracts/blob/master/Foundation/Application.php 

82https://github.com/illuminate/contracts/blob/master/Hashing/Hasher.php 

83https://github.com/illuminate/contracts/blob/master/Logging/Log.php 

84https://github.com/illuminate/contracts/blob/master/Mail/MailQueue.php 

85https://github.com/illuminate/contracts/blob/master/Mail/Mailer.php 

86https://github.com/illuminate/contracts/blob/master/Queue/Factory.php 

87https://github.com/illuminate/contracts/blob/master/Queue/Queue.php 

88https://github.com/illuminate/contracts/blob/master/Redis/Database.php 

89https://github.com/illuminate/contracts/blob/master/Routing/Registrar.php 

90https://github.com/illuminate/contracts/blob/master/Routing/ResponseFactory.php 
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sRoutingUrlGenerator91  | URL  IlluminateContractsSupportArrayable92  | IlluminateContractsSup- 
portjsonable93 1 IlluminateContractsSupportRenderable94 1 IlluminateContractsValidationFactory95 
| Validator::make()  IlluminateContractsValidationValidator96  | IlluminateContractsViewFactory97  | 
View::make()  IlluminateContractsViewView98  | 


How  To  Use  Contracts 

So,  how  do  you  get  an  implementation  of  a contract?  It’s  actually  quite  simple. 

Many  types  of  classes  in  Laravel  are  resolved  through  the  service  container,  including  controllers, 
event  listeners,  middleware,  queued  jobs,  and  even  route  Closures.  So,  to  get  an  implementation  of 
a contract,  you  can  just  “type-hint”  the  interface  in  the  constructor  of  the  class  being  resolved. 

For  example,  take  a look  at  this  event  listener: 

1 < ?php 

2 

3 namespace  App\Listeners; 

4 

5 use  App\User; 

6 use  App\Events\NewUserRegistered; 

7 use  1 1 luminate\Contracts\Redis\Database; 

8 

9 class  CacheUserlnformation 


10  { 

11 

/** 

12 

* The  Red is  database 

i mp 1 emen tat  ion . 

13 

*/ 

14 

protected  $redis; 

15 

16 

/** 

17 

* Create  a new  event 

handler  instance 

18 

* 

19 

* §param  Database 

$redi s 

20 

* §return  void 

21 

*/ 

91https://github.com/illuminate/contracts/blob/master/Routing/UrlGenerator.php 

92https://github.com/illuminate/contracts/blob/master/Support/Arrayable.php 

93https://github.com/illuminate/contracts/blob/master/Support/Jsonable.php 

94https://github.com/illuminate/contracts/blob/master/Support/Renderable.php 

95https://github.com/illuminate/contracts/blob/master/Validation/Factory.php 

96https://github.com/illuminate/contracts/blob/master/Validation/Validator.php 

97https://github.com/illuminate/contracts/blob/master/View/Factory.php 

98https://gi  thub.com/illuminate/contracts/blob/master/View/View.php 
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public  function  construct( Database  $redis) 

23  { 

24  $this- >redis  = $redis; 

25  } 

26 

27  /** 

28  * Handle  the  event. 

29  * 

30  * §param  Newilser Registered  $event 

31  * §return  void 

32  */ 

public  function  handle(NewUserRegistered  $event) 

34  { 

35  // 

36  } 

37  } 


When  the  event  listener  is  resolved,  the  service  container  will  read  the  type-hints  on  the  constructor 
of  the  class,  and  inject  the  appropriate  value.  To  learn  more  about  registering  things  in  the  service 
container,  check  out  its  documentation. 


Facades 


• Introduction 

• Using  Facades 

• Facade  Class  Reference 

Introduction 


Facades  provide  a “static”  interface  to  classes  that  are  available  in  the  application’s  service  container. 
Laravel  ships  with  many  facades,  and  you  have  probably  been  using  them  without  even  knowing  it! 
Laravel  “facades”  serve  as  “static  proxies”  to  underlying  classes  in  the  service  container,  providing 
the  benefit  of  a terse,  expressive  syntax  while  maintaining  more  testability  and  flexibility  than 
traditional  static  methods. 

Using  Facades 

In  the  context  of  a Laravel  application,  a facade  is  a class  that  provides  access  to  an  object  from  the 
container.  The  machinery  that  makes  this  work  is  in  the  Facade  class.  Laravel’s  facades,  and  any 
custom  facades  you  create,  will  extend  the  base  1 1 luminate\Support\Facades\Facade  class. 

A facade  class  only  needs  to  implement  a single  method:  getFacadeAccessor.  It’s  the  getFacadeAc- 
cessor  method’s  job  to  define  what  to  resolve  from  the  container.  The  Facade  base  class  makes  use 
of  the cal  lStatic( ) magic-method  to  defer  calls  from  your  facade  to  the  resolved  object. 

In  the  example  below,  a call  is  made  to  the  Laravel  cache  system.  By  glancing  at  this  code,  one  might 
assume  that  the  static  method  get  is  being  called  on  the  Cache  class: 


1 < ?php 

2 

3 namespace  App\Http\Control lers; 

4 

5 use  Cache; 

6 use  App\Http\Controllers\Controller; 

7 

8 class  UserController  extends  Controller 

9 { 

10  /** 

11  * Show  the  profile  for  the  given  user. 

12  * 
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13  * §param  int  $id 

14  * §return  Response 

15  */ 

16  public  function  showProf i le($id) 

17  { 

18  $user  = Cache :: get( ' user $id) ; 

19 

return  view( ' prof i le ' , ['user'  =>  $user]); 

21  } 

22  } 


Notice  that  near  the  top  of  the  file  we  are  “importing”  the  Cache  facade.  This  facade  serves  as  a 
proxy  to  accessing  the  underlying  implementation  of  the  1 1 luminate\Contracts\Cache\Factory 
interface.  Any  calls  we  make  using  the  facade  will  be  passed  to  the  underlying  instance  of  Laravel’s 
cache  service. 

If  we  look  at  that  1 1 luminate\Support\Facades\Cache  class,  you’ll  see  that  there  is  no  static  method 
get: 


1 class  Cache  extends  Facade 

2 { 

3 /** 

4 * Get  the  registered  name  of  the  component. 

5 * 

6 * ©return  string 

7 */ 

protected  static  function  getFacadeAccessor ( ) { return  'cache';  } 

9 1 


Instead,  the  Cache  facade  extends  the  base  Facade  class  and  defines  the  method  getFacadeAcces- 
sor( ).  Remember,  this  method’s  job  is  to  return  the  name  of  a service  container  binding.  When  a 
user  references  any  static  method  on  the  Cache  facade,  Laravel  resolves  the  cache  binding  from  the 
service  container  and  runs  the  requested  method  (in  this  case,  get)  against  that  object. 
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Facade  Class  Reference 


Below  you  will  find  every  facade  and  its  underlying  class.  This  is  a useful  tool  for  quickly  digging  into 
the  API  documentation  for  a given  facade  root.  The  service  container  binding  key  is  also  included 
where  applicable. 


Facade 


Class 


Service  Container  Binding 


App 

IlluminateFoundationApplication^jbp 

Artisan 

IlluminateContractsConsoleKerndPPisan 

Auth 

IlluminateAuthAuthManager101  auth 

Blade 

IlluminateViewCompilersBladeCtwlqjiieidSinp  i 1 er 

Bus 

IlluminateContractsBusDispatcher103 

Cache 

IlluminateCacheRepository104  cache 

Config 

IlluminateConfigRepository105  config 

Cookie 

IlluminateCookieCookieJar106  cook  i e 

Crypt 

IlluminateEncryptionEncrypter10bncrypter 

DB 

IlluminateDatabaseDatabaseMandger108 

DB  (Instance) 

IlluminateDatabaseConnection109 

Event 

IlluminateEventsDispatcher110  events 

File 

IlluminateFilesystemFilesystem11^  i 1 es 

Gate 

IlluminateContractsAuthAccessGate112 

Hash 

IlluminateContractsHashingHasheaPf 

99http://laravel.com/api/\protect\char”007B\relax\protect\char”007B\relaxversion\protect\char”007D\relax\protect\char”007D\relax/Illuminate/ 
Foundation/ Application.html 

lo°http://laravel.com/api/\protect\char”007B\relax\protect\char”007B\relaxversion\protect\char”007D\relax\protect\char”007D\relax/Illuminate/ 

Contracts/Console/Kernel.html 

lolhttp://laravel.com/api/\protect\char”007B\relax\protect\char”007B\relaxversion\protect\char”007D\relax\protect\char”007D\relax/Illuminate/ 
Auth/ AuthManager.html 

lo2http://laravel.com/api/\protect\char”007B\relax\protect\char”007B\relaxversion\protect\char”007D\relax\protect\char”007D\relax/Illuminate/ 

View/Compilers/BladeCompiler.html 

lo3http://laravel.com/api/\protect\char”007B\relax\protect\char”007B\relaxversion\protect\char”007D\relax\protect\char”007D\relax/Illuminate/ 

Contracts/Bus/Dispatcher.html 

104http://laravel.com/api/\protect\char”007B\relax\protect\char”007B\relaxversion\protect\char”007D\relax\protect\char”007D\relax/Illuminate/ 

Cache/Repository.html 

105http://laravel.com/api/\protect\char”007B\relax\protect\char”007B\relaxversion\protect\char”007D\relax\protect\char”007D\relax/Illuminate/ 

Config/Repository.html 

106http://laravel.com/api/\protect\char”007B\relax\protect\char”007B\relaxversion\protect\char”007D\relax\protect\char”007D\relax/Illuminate/ 

Cookie/Cookiejar.html 

107http://laravel.com/api/\protect\char”007B\relax\protect\char”007B\relaxversion\protect\char”007D\relax\protect\char”007D\relax/Illuminate/ 

Encryption/Encrypter.html 

108http://laravel.com/api/\protect\char”007B\relax\protect\char”007B\relaxversion\protect\char”007D\relax\protect\char”007D\relax/Illuminate/ 

Database/DatabaseManager.html 

109http://laravel.com/api/\protect\char”007B\relax\protect\char”007B\relaxversion\protect\char”007D\relax\protect\char”007D\relax/Illuminate/ 

Database/Connection.html 

110http://laravel.com/api/\protect\char”007B\relax\protect\char”007B\relaxversion\protect\char”007D\relax\protect\char”007D\relax/Illuminate/ 

Events/Dispatcher.html 

111http://laravel.com/api/\protect\char”007B\relax\protect\char”007B\relaxversion\protect\char”007D\relax\protect\char”007D\relax/Illuminate/ 

Filesystem/Filesystem.html 

112http://laravel.com/api/5.1/Illuminate/Contracts/Auth/Access/Gate.html 

113http://laravel.com/api/\protect\char”007B\relax\protect\char”007B\relaxversion\protect\char”007D\relax\protect\char”007D\relax/Illuminate/ 

Contracts/Hashing/Hasher.html 
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Facade 


Class 


Service  Container  Binding 


Lang 

Log 

Mail 

Password 

Queue 

Queue  (Instance) 

Queue  (Base  Class) 

Redirect 

Redis 

Request 

Response 

Route 

Schema 

Session 

Session  (Instance) 

Storage 

URL 

Validator 


1 1 lu  mi  nateTransl  ati  onTranslator 1 'tr  anslator 


IlluminateLogWriter115 

IlluminateMailMailer116 


log 

mailer 


IlluminateAuthPasswordsPasswoadiBHohaB^foord 

IlluminateQueueQueueManageCtfueue 

IlluminateContractsQueueQueuefcjueue 

IlluminateQueueQueue120 

IlluminateRoutingRedirector121  red  i rect 

IlluminateRedisDatabase122  redis 

IlluminateHttpRequest123  request 

IlluminateContractsRoutingResponseFactory124 

IlluminateRoutingRouter125  router 

IlluminateDatabaseSchemaBlueprint126 

IlluminateSessionSessionManage^bsion 

IlluminateSessionStore128 

IlluminateContractsFilesystemFacftblrys^stem 

IlluminateRoutingUrlGenerator13Eirl 

IlluminateValidationFactory131  validator 


114http://laravel.com/api/\protect\char”007B\relax\protect\char”007B\relaxversion\protect\char”007D\relax\protect\char”007D\relax/Illuminate/ 
T ranslation/T  ranslator.html 

115http://laravel.com/api/\protect\char”007B\relax\protect\char”007B\relaxversion\protect\char”007D\relax\protect\char”007D\relax/Illuminate/ 

Log/Writer.html 

116http://laravel.com/api/\protect\char”007B\relax\protect\char”007B\relaxversion\protect\char”007D\relax\protect\char”007D\relax/Illuminate/ 

Mail/Mailer.html 

117http://laravel.com/api/\protect\char”007B\relax\protect\char”007B\relaxversion\protect\char”007D\relax\protect\char”007D\relax/Illuminate/ 

Auth/Passwords/PasswordBroker.html 

118http://laravel.com/api/\protect\char”007B\relax\protect\char”007B\relaxversion\protect\char”007D\relax\protect\char”007D\relax/Illuminate/ 

Queue/QueueManager.html 

119http://laravel.com/api/\protect\char”007B\relax\protect\char”007B\relaxversion\protect\char”007D\relax\protect\char”007D\relax/Illuminate/ 

Contracts/Queue/Queue.html 

12°http://laravel.com/api/\protect\char”007B\relax\protect\char”007B\relaxversion\protect\char”007D\relax\protect\char”007D\relax/Illuminate/ 

Queue/Queue.html 

121http://laravel.com/api/\protect\char”007B\relax\protect\char”007B\relaxversion\protect\char”007D\relax\protect\char”007D\relax/Illuminate/ 

Routing/Redirector.html 

122http://laravel.com/api/\protect\char”007B\relax\protect\char”007B\relaxversion\protect\char”007D\relax\protect\char”007D\relax/Illuminate/ 

Redis/Database.html 

123http://laravel.com/api/\protect\char”007B\relax\protect\char”007B\relaxversion\protect\char”007D\relax\protect\char”007D\relax/Illuminate/ 

Http/Request.html 

124http://laravel.com/api/\protect\char”007B\relax\protect\char”007B\relaxversion\protect\char”007D\relax\protect\char”007D\relax/Illuminate/ 

Contracts/Routing/ResponseFactory.html 

125http://laravel.com/api/\protect\char”007B\relax\protect\char”007B\relaxversion\protect\char”007D\relax\protect\char”007D\relax/Illuminate/ 

Routing/Router.html 

126http://laravel.com/api/\protect\char”007B\relax\protect\char”007B\relaxversion\protect\char”007D\relax\protect\char”007D\relax/Illuminate/ 

Database/Schema/Blueprint.html 

127http://laravel.com/api/\protect\char”007B\relax\protect\char”007B\relaxversion\protect\char”007D\relax\protect\char”007D\relax/Illuminate/ 

Session/SessionManager.html 

128http://laravel.com/api/\protect\char”007B\relax\protect\char”007B\relaxversion\protect\char”007D\relax\protect\char”007D\relax/Illuminate/ 

Session/Store.html 

129http://laravel.com/api/\protect\char”007B\relax\protect\char”007B\relaxversion\protect\char”007D\relax\protect\char”007D\relax/Illuminate/ 

Contracts/Filesystem/Factory.html 

13°http://laravel.com/api/\protect\char”007B\relax\protect\char”007B\relaxversion\protect\char”007D\relax\protect\char”007D\relax/Illuminate/ 

Routing/UrlGenerator.html 

131http://laravel.com/api/\protect\char”007B\relax\protect\char”007B\relaxversion\protect\char”007D\relax\protect\char”007D\relax/Illuminate/ 
V alidation/Factory . html 
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Facade  Class  Service  Container  Binding 

Validator  (Instance)  IlluminateValidationValidator132 
View  IlluminateViewFactory133  view 

View  (Instance)  IlluminateViewView134 


132http://laravel.com/api/\protect\char”007B\relax\protect\char”007B\relaxversion\protect\char”007D\relax\protect\char”007D\relax/Illuminate/ 
V alidation/ V alidator.html 

133http://laravel.com/api/\protect\char”007B\relax\protect\char”007B\relaxversion\protect\char”007D\relax\protect\char”007D\relax/Illuminate/ 

View/Factory.html 

134http://laravel.com/api/\protect\char”007B\relax\protect\char”007B\relaxversion\protect\char”007D\relax\protect\char”007D\relax/Illuminate/ 
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• Introduction  A>  - Database  Considerations 

• Authentication  Quickstart  A>  - Routing  A>  - Views  A>  - Authenticating  A>  - Retrieving  The 
Authenticated  User  A>  - Protecting  Routes  A>  - Authentication  Throttling 

• Manually  Authenticating  Users  A>  - Remembering  Users  A>  - Other  Authentication  Methods 

• HTTP  Basic  Authentication  A>  - Stateless  HTTP  Basic  Authentication 

• Resetting  Passwords  A>  - Database  Considerations  A>  - Routing  A>  - Views  A>  - After 
Resetting  Passwords  A>  - Customization 

• Social  Authentication135 

• Adding  Custom  Guards 

• Adding  Custom  User  Providers 

• Events 

Introduction 

Laravel  makes  implementing  authentication  very  simple.  In  fact,  almost  everything  is  configured 
for  you  out  of  the  box.  The  authentication  configuration  file  is  located  at  conf  ig/auth . php,  which 
contains  several  well  documented  options  for  tweaking  the  behavior  of  the  authentication  services. 

At  its  core,  Laravel’s  authentication  facilities  are  made  up  of  “guards”  and  “providers”.  Guards  define 
how  user’s  are  authenticated  for  each  request.  For  example,  Laravel  ships  with  a session  guard 
which  maintains  state  using  session  storage  and  cookies  and  a token  guard,  which  authenticates 
users  using  a “API  token”  that  is  passed  with  each  request. 

Providers  define  how  users  are  retrieved  from  your  persistent  storage.  Laravel  ships  with  support 
for  retrieving  users  using  Eloquent  and  the  database  query  builder.  However,  you  are  free  to  define 
additional  providers  as  needed  for  your  application. 

Don’t  worry  if  this  all  sounds  confusing  now!  Most  applications  will  never  need  to  modify  the  default 
authentication  configuration. 


Database  Considerations 

By  default,  Laravel  includes  an  App\User  Eloquent  model  in  your  app  directory.  This  model  may  be 
used  with  the  default  Eloquent  authentication  driver.  If  your  application  is  not  using  Eloquent,  you 
may  use  the  database  authentication  driver  which  uses  the  Laravel  query  builder. 

135https://github.com/laravel/socialite 
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When  building  the  database  schema  for  the  App\User  model,  make  sure  the  password  column  is  at 
least  60  characters  in  length. 

Also,  you  should  verify  that  your  users  (or  equivalent)  table  contains  a nullable,  string  remember_- 
token  column  of  100  characters.  This  column  will  be  used  to  store  a token  for  “remember  me”  sessions 
being  maintained  by  your  application.  This  can  be  done  by  using  Stable- >rememberToken( ) ; in  a 
migration. 

Authentication  Quickstart 

Laravel  ships  with  two  authentication  controllers  out  of  the  box,  which  are  located  in  theApp\Http\Control  1 
namespace.  The  AuthControl  ler  handles  new  user  registration  and  authentication,  while  the 
PasswordControl  ler  contains  the  logic  to  help  existing  users  reset  their  forgotten  passwords.  Each 
of  these  controllers  uses  a trait  to  include  their  necessary  methods.  For  many  applications,  you  will 
not  need  to  modify  these  controllers  at  all. 

Routing 

Laravel  provides  a quick  way  to  scaffold  all  of  the  routes  and  views  you  need  for  authentication 
using  one  simple  command: 

1 php  artisan  make:auth 


This  command  should  be  used  on  fresh  applications  and  will  install  registration  and  login  views, 
as  well  as  routes  for  all  authentication  end-points.  A HomeControl  ler  will  also  be  generated,  which 
serves  post-login  requests  to  your  application’s  dashboard.  However,  you  are  free  to  customize  or 
even  remove  this  controller  based  on  the  needs  of  your  application. 

Views 

As  mentioned  in  the  previous  section,  the  php  artisan  make : auth  command  will  create  all  of  the 
views  you  need  for  authentication  and  place  them  in  the  resources/views/auth  directory. 

The  make: auth  command  will  also  create  a resources/views/layouts  directory  containing  a base 
layout  for  your  application.  All  of  these  views  use  the  Bootstrap  CSS  framework,  but  you  are  free 
to  customize  them  however  you  wish. 

Authenticating 

Now  that  you  have  routes  and  views  setup  for  the  included  authentication  controllers,  you  are  ready 
to  register  and  authenticate  new  users  for  your  application!  You  may  simply  access  your  application 
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in  a browser.  The  authentication  controllers  already  contain  the  logic  (via  their  traits)  to  authenticate 
existing  users  and  store  new  users  in  the  database. 

Path  Customization 

When  a user  is  successfully  authenticated,  they  will  be  redirected  to  the  / URI.  You  can  customize 
the  post-authentication  redirect  location  by  defining  a red  irectTo  property  on  the  AuthControl  ler: 

1 protected  SredirectTo  = '/home'; 


When  a user  is  not  successfully  authenticated,  they  will  be  redirected  back  to  the  login  form  location 
automatically. 

Guard  Customization 


You  may  also  customize  the  “guard”  that  is  used  to  authenticate  users.  To  get  started,  define  a guard 
property  on  your  AuthControl  ler.  The  value  of  this  property  should  correspond  with  one  of  the 
guards  configured  in  your  auth . php  configuration  file: 


1 protected  $guard  = 'admin'; 


Validation  / Storage  Customization 

To  modify  the  form  fields  that  are  required  when  a new  user  registers  with  your  application, 
or  to  customize  how  new  user  records  are  inserted  into  your  database,  you  may  modify  the 
AuthControl  ler  class.  This  class  is  responsible  for  validating  and  creating  new  users  of  your 
application. 

The  validator  method  of  the  AuthControl  ler  contains  the  validation  rules  for  new  users  of  the 
application.  You  are  free  to  modify  this  method  as  you  wish. 

The  create  method  of  the  AuthControl  ler  is  responsible  for  creating  new  App\User  records  in  your 
database  using  the  Eloquent  ORM.  You  are  free  to  modify  this  method  according  to  the  needs  of  your 
database. 


Retrieving  The  Authenticated  User 

You  may  access  the  authenticated  user  via  the  Auth  facade: 
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1 $user  = Auth : : user( ) ; 


Alternatively,  once  a user  is  authenticated,  you  may  access  the  authenticated  user  via  an  I Hu- 
miliate \Http\Request  instance.  Remember,  type-hinted  classes  will  automatically  be  injected  into 
your  controller  methods: 


1 < ?php 

2 

3 namespace  App\Http\Control lers; 

4 

5 use  1 1 luminate\Http\Request; 

6 

7 class  Prof i leControl ler  extends  Controller 

8 { 

g /** 

10  * Update  the  user's  profile. 

11  * 

12  * §param  Request  $request 

13  * §return  Response 

14  */ 

15  public  function  updateProf i le(Request  $request) 

16  { 

17  if  (Srequest- >user( ) ) { 

18  //  $request- >user( ) returns  an  instance  of  the  authenticated  user.  . . 

19  } 

20  } 

21  } 


Determining  If  The  Current  User  Is  Authenticated 

To  determine  if  the  user  is  already  logged  into  your  application,  you  may  use  the  check  method  on 
the  Auth  facade,  which  will  return  true  if  the  user  is  authenticated: 


1 if  (Auth : : check( ) ) { 

//  The  user  is  logged  in. . . 

3 } 
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However,  you  may  use  middleware  to  verify  that  the  user  is  authenticated  before  allowing  the  user 
access  to  certain  routes  / controllers.  To  learn  more  about  this,  check  out  the  documentation  on 
protecting  routes. 

Protecting  Routes 


Route  middleware  can  be  used  to  allow  only  authenticated  users  to  access  a given  route.  Laravel 
ships  with  the  auth  middleware,  which  is  defined  in  app\Http\Middleware\Authenticate.  php.  All 
you  need  to  do  is  attach  the  middleware  to  a route  definition: 


1 

//  Using  A Route  Closure... 

2 

3 

Route :: get( ' prof i le 1 , ['middleware'  =>  'auth' 

function!)  1 

4 

//  Only  authenticated  users  may  enter. . . 

5 

11); 

6 

7 

//  Using  A Controller. . . 

8 

9 

Route :: get( ' prof i le 1 , [ 

10 

'middleware'  =>  'auth', 

11 

’uses’  =>  ' Prof i leControl ler@show ’ 

12 

]); 

Of  course,  if  you  are  using  controller  classes,  you  may  call  the  middleware  method  from  the 
controller’s  constructor  instead  of  attaching  it  in  the  route  definition  directly: 


1 public  function  construct!) 

2 { 

$this- >middleware( 'auth' ); 

4 } 


Specifying  A Guard 

When  attaching  the  auth  middleware  to  a route,  you  may  also  specify  which  guard  should  be  used 
to  perform  the  authentication: 
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1 

2 

3 

4 


Route :: get( ' prof i le 1 , [ 

'middleware'  =>  'auth:api', 

'uses'  =>  ' Prof i leControl ler@show ' 


]); 


The  guard  specified  should  correspond  to  one  of  the  keys  in  the  guards  array  of  your  auth . php 
configuration  file. 

Authentication  Throttling 

If  you  are  using  Laravel’s  built-in  AuthContro  1 ler  class,  the  1 1 luminate\Foundation\Auth\Throttlesl_ogins 
trait  may  be  used  to  throttle  login  attempts  to  your  application.  By  default,  the  user  will  not  be  able 
to  login  for  one  minute  if  they  fail  to  provide  the  correct  credentials  after  several  attempts.  The 
throttling  is  unique  to  the  user’s  username  / e-mail  address  and  their  IP  address: 

1 < ?php 

2 

3 namespace  App\Http\Control lers\Auth; 

4 

5 use  App\User; 

6 use  Validator; 

7 use  App\Http\Control lers\Control ler ; 

8 use  Illuminate\Foundation\Auth\ThrottlesLogins; 

9 use  1 1 luminate\Foundation\Auth\AuthenticatesAndRegistersllsers; 

10 

11  class  AuthController  extends  Controller 

12  { 

13  use  AuthenticatesAndRegistersUsers,  ThrottlesLogins; 

14 

15  //  Rest  of  AuthController  class. . . 

16  } 


Manually  Authenticating  Users 

Of  course,  you  are  not  required  to  use  the  authentication  controllers  included  with  Laravel.  If  you 
choose  to  remove  these  controllers,  you  will  need  to  manage  user  authentication  using  the  Laravel 
authentication  classes  directly.  Don’t  worry,  it’s  a cinch! 
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We  will  access  Laravel’s  authentication  services  via  the  Auth  facade,  so  we’ll  need  to  make  sure  to 
import  the  Auth  facade  at  the  top  of  the  class.  Next,  let’s  check  out  the  attempt  method: 


1 

2 

3 

4 

5 

6 

7 

8 
9 

10 

11 

12 

13 

14 

15 

16 

17 

18 

19 

20 
21 


<?php 

namespace  App\Http\Control lers; 
use  Auth; 

class  AuthController  extends  Controller 

{ 

/** 

* Handle  an  authentication  attempt. 

* 

* @return  Response 
*/ 

public  function  authenticate( ) 

{ 

if  (Auth  : attempt( [ ' emai 1 ' =>  $email,  'password' 
//  Authentication  passed.  . . 
return  redirect( ) - > intended( ' dashboard ' ) ; 

} 

1 

} 


$password]))  { 


The  attempt  method  accepts  an  array  of  key  / value  pairs  as  its  first  argument.  The  values  in  the 
array  will  be  used  to  find  the  user  in  your  database  table.  So,  in  the  example  above,  the  user  will  be 
retrieved  by  the  value  of  the  email  column.  If  the  user  is  found,  the  hashed  password  stored  in  the 
database  will  be  compared  with  the  hashed  password  value  passed  to  the  method  via  the  array.  If 
the  two  hashed  passwords  match  an  authenticated  session  will  be  started  for  the  user. 

The  attempt  method  will  return  true  if  authentication  was  successful.  Otherwise,  false  will  be 
returned. 

The  intended  method  on  the  redirector  will  redirect  the  user  to  the  URL  they  were  attempting  to 
access  before  being  caught  by  the  authentication  filter.  A fallback  URI  may  be  given  to  this  method 
in  case  the  intended  destination  is  not  available. 


Specifying  Additional  Conditions 

If  you  wish,  you  also  may  add  extra  conditions  to  the  authentication  query  in  addition  to  the  user’s 
e-mail  and  password.  For  example,  we  may  verify  that  user  is  marked  as  “active”: 
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1  if  (Auth : : attempt( [ 1 emai 1 ' =>  Semail,  'password'  =>  $password,  'active'  =>  1]))  { 
//  The  user  is  active,  not  suspended,  and  exists. 

3 } 


Note:  In  these  examples,  email  is  not  a required  option,  it  is  merely  used  as  an  example. 
You  should  use  whatever  column  name  corresponds  to  a “username”  in  your  database. 


Accessing  Specific  Guard  Instances 

You  may  specify  which  guard  instance  you  would  like  to  utilize  using  the  guard  method  on  the 
Auth  facade.  This  allows  you  to  manage  authentication  for  separate  parts  of  your  application  using 
entirely  separate  authenticatable  models  or  user  tables. 

The  guard  name  passed  to  the  guard  method  should  correspond  to  one  of  the  guards  configured  in 
your  auth . php  configuration  file: 


1 if  (Auth :: guard( ' admin ')- >attempt($credentials) ) { 

2 // 

3 } 


Logging  Out 

To  log  users  out  of  your  application,  you  may  use  the  logout  method  on  the  Auth  facade.  This  will 
clear  the  authentication  information  in  the  user’s  session: 

1 Auth : : logout( ) ; 


Remembering  Users 

If  you  would  like  to  provide  “remember  me”  functionality  in  your  application,  you  may  pass  a 
boolean  value  as  the  second  argument  to  the  attempt  method,  which  will  keep  the  user  authenticated 
indefinitely,  or  until  they  manually  logout.  Of  course,  your  users  table  must  include  the  string 
remember_token  column,  which  will  be  used  to  store  the  “remember  me”  token. 
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1  if  (Auth : : attempt( [ ' emai 1 ' =>  Semail,  'password'  =>  $password] , $remember))  { 
//  The  user  is  being  remembered... 

3 } 


If  you  are  “remembering”  users,  you  may  use  the  viaRemember  method  to  determine  if  the  user  was 
authenticated  using  the  “remember  me”  cookie: 


1 if  (Auth : : viaRemember ( ) ) { 

2 // 

3 } 


Other  Authentication  Methods 

Authenticate  A User  Instance 

If  you  need  to  log  an  existing  user  instance  into  your  application,  you  may  call  the  login 
method  with  the  user  instance.  The  given  object  must  be  an  implementation  of  the  Illumi- 
nate\Contracts\Auth\Authenticatable  contract.  Of  course,  the  App\User  model  included  with 
Laravel  already  implements  this  interface: 

1 Auth : : login($user ) ; 


Authenticate  A User  By  ID 

To  log  a user  into  the  application  by  their  ID,  you  may  use  the  loginUsingld  method.  This  method 
simply  accepts  the  primary  key  of  the  user  you  wish  to  authenticate: 

1 Auth : : loginUsing!d(l ) ; 


Authenticate  A User  Once 

You  may  use  the  once  method  to  log  a user  into  the  application  for  a single  request.  No  sessions  or 
cookies  will  be  utilized,  which  may  be  helpful  when  building  a stateless  API.  The  once  method  has 
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the  same  signature  as  the  attempt  method: 


1 if  (Auth : :once($credentials) ) { 

2 // 

3 } 


HTTP  Basic  Authentication 

HTTP  Basic  Authentication136  provides  a quick  way  to  authenticate  users  of  your  application  without 
setting  up  a dedicated  “login”  page.  To  get  started,  attach  the  auth . basic  middleware  to  your  route. 
The  auth . basic  middleware  is  included  with  the  Laravel  framework,  so  you  do  not  need  to  define 
it: 

1 Route :: get( ' prof i le 1 , ['middleware'  =>  ' auth . basic ' , function()  { 

//  Only  authenticated  users  may  enter. . . 

3 }]); 


Once  the  middleware  has  been  attached  to  the  route,  you  will  automatically  be  prompted  for 
credentials  when  accessing  the  route  in  your  browser.  By  default,  the  auth . basic  middleware  will 
use  the  email  column  on  the  user  record  as  the  “username”. 

A Note  On  FastCGI 

If  you  are  using  PHP  FastCGI,  HTTP  Basic  authentication  may  not  work  correctly  out  of  the  box. 
The  following  lines  should  be  added  to  your  . htaccess  file: 

1 RewriteCond  %{HTTP : Author ization}  A(.+)$ 

2 Rewr iteRule  .*  - [E=HTTP_AUTHOR IZATION : %{HTTP  Authorization} ] 


Stateless  HTTP  Basic  Authentication 

You  may  also  use  HTTP  Basic  Authentication  without  setting  a user  identifier  cookie  in  the  session, 
which  is  particularly  useful  for  API  authentication.  To  do  so,  define  a middleware  that  calls  the 

136http://en.  wikipedia.org/wiki/Basic_access_authentication 
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onceBasic  method.  If  no  response  is  returned  by  the  onceBasic  method,  the  request  may  be  passed 
further  into  the  application: 


1 < ?php 

2 

3 namespace  1 1 luminate\Auth\Middleware; 

4 

5 use  Auth ; 

6 use  Closure; 

7 

8 class  AuthenticateOnceWithBasicAuth 

9 { 

10  /** 

11  * Handle  an  incoming  request. 

12  * 

13  * §param  \Illuminate\Http\Request  $request 

14  * §param  \Closure  $next 

15  * @return  mixed 

16  */ 

public  function  handle($request,  Closure  $next) 
18  { 

return  Auth . : onceBasic( ) ?:  $next($request) ; 

20  } 

21 

22  } 


Next,  register  the  route  middleware  and  attach  it  to  a route: 


1 

Route : 

get( 

api/user',  ['middleware'  =>  1 auth . basic . once ' 

function()  { 

2 

// 

Only 

authenticated  users  may  enter. . . 

3 

}]); 

Resetting  Passwords 

Database  Considerations 

Most  web  applications  provide  a way  for  users  to  reset  their  forgotten  passwords.  Rather  than  forcing 
you  to  re-implement  this  on  each  application,  Laravel  provides  convenient  methods  for  sending 
password  reminders  and  performing  password  resets. 
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To  get  started,  verify  that  your  App\User  model  implements  the  1 1 luminate\Contracts\Auth\CanResetPassword 
contract.  Of  course,  the  App\User  model  included  with  the  framework  already  implements  this 
interface,  and  uses  the  Illuminate\Auth\Passwords\CanResetPassword  trait  to  include  the  methods 
needed  to  implement  the  interface. 

Generating  The  Reset  Token  Table  Migration 

Next,  a table  must  be  created  to  store  the  password  reset  tokens.  The  migration  for  this  table  is 
included  with  Laravel  out  of  the  box,  and  resides  in  the  database/migrations  directory.  So,  all  you 
need  to  do  is  migrate: 

1 php  artisan  migrate 


Routing 

Laravel  includes  an  Auth\PasswordController  that  contains  the  logic  necessary  to  reset  user 
passwords.  All  of  the  routes  needed  to  perform  password  resets  may  be  generated  using  the 
make:auth  Artisan  command: 

1 php  artisan  make:auth 


Views 

Again,  Laravel  will  generate  all  of  the  necessary  views  for  password  reset  when  the  make:auth 
command  is  executed.  These  views  are  placed  in  resources/views/auth/passwords.  You  are  free 
to  customize  them  as  needed  for  your  application. 

After  Resetting  Passwords 

Once  you  have  defined  the  routes  and  views  to  reset  your  user’s  passwords,  you  may  simply 
access  the  route  in  your  browser  at  /password/reset.  The  PasswordControl  ler  included  with  the 
framework  already  includes  the  logic  to  send  the  password  reset  link  e-mails  as  well  as  update 
passwords  in  the  database. 

After  the  password  is  reset,  the  user  will  automatically  be  logged  into  the  application  and  redirected 
to  /home.  You  can  customize  the  post  password  reset  redirect  location  by  defining  a redirectTo 
property  on  the  PasswordControl  ler: 
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1 protected  $redirectTo  = '/dashboard'; 


Note:  By  default,  password  reset  tokens  expire  after  one  hour.  You  may  change  this  via  the 
password  reset  expire  option  in  your  conf  ig/auth . php  fde. 


Customization 

Authentication  Guard  Customization 

In  your  auth . php  configuration  file,  you  may  configure  multiple  “guards”,  which  may  be  used  to 
define  authentication  behavior  for  multiple  user  tables.  You  can  customize  the  included  Password  - 
Controller  to  use  the  guard  of  your  choice  by  adding  a $guard  property  to  the  controller: 

1 /** 

2 * The  authentication  guard  that  should  be  used. 

3 * 

4 * @var  string 

5 V 

6 protected  Sguard  'admins’; 


Password  Broker  Customization 


In  your  auth . php  configuration  file,  you  may  configure  multiple  password  “brokers”,  which  may  be 
used  to  reset  passwords  on  multiple  user  tables.  You  can  customize  the  included  PasswordControl  ler 
to  use  the  broker  of  your  choice  by  adding  a $broker  property  to  the  controller: 


1 /** 

2 * The  password  broker  that  should  be  used. 

3 * 

4 * §var  string 

5 */ 

6 protected  Sbroker  - 'admins'; 
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Adding  Custom  Guards 

You  may  define  your  own  authentication  guards  using  the  extend  method  on  the  Auth  facade.  You 
should  place  this  call  to  provider  within  a service  provider: 

1 < ?php 

2 

3 namespace  App\Providers; 

4 

5 use  Auth; 

6 use  App\Services\Auth\JwtGuard; 

7 use  Illuminate\Support\ServiceProvider; 

8 

9 class  AuthServiceProvider  extends  ServiceProvider 

10  { 

11  /** 

12  * Perform  post-registration  booting  of  services. 

13  * 

14  * § return  void 

15  */ 

16  public  function  boot() 

17  { 

18  Auth :: extend (' jwt ' , function($app,  $name,  array  $config)  { 

19  //  Return  an  instance  of  1 1 luminate\Contracts\Auth\Guard . . . 

20 

21  return  new  JwtGuard(Auth  : createllserProvider($conf ig [' provider  1 ])) ; 

22  }); 

23  } 

24 

25  /** 

26  * Register  bindings  in  the  container . 

27  * 

28  * §return  void 

29  */ 

30  public  function  register() 

31  { 

32  // 

33  } 

34  } 


As  you  can  see  in  the  example  above,  the  callback  passed  to  the  extend  method  should  return  an 
implementation  of  Illuminate\Contracts\Auth\Guard.  This  interface  contains  a few  methods  you 
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will  need  to  implement  to  define  a custom  guard. 

Once  your  custom  guard  has  been  defined,  you  may  use  the  guard  in  your  guards  configuration: 

1 'guards'  =>  [ 

' api ' =>  [ 

' driver ' =>  ' jwt ' , 

4 'provider'  =>  'users', 

5 ], 

6 ], 


Adding  Custom  User  Providers 

If  you  are  not  using  a traditional  relational  database  to  store  your  users,  you  will  need  to  extend 
Laravel  with  your  own  authentication  user  provider.  We  will  use  the  provider  method  on  the  Auth 
facade  to  define  a custom  user  provider.  You  should  place  this  call  to  provider  within  a service 
provider: 

1 < ?php 

2 

3 namespace  App\Providers; 

4 

5 use  Auth; 

6 use  App\Extensions\RiakllserProvider ; 

7 use  Illuminate\Support\ServiceProvider; 

8 

9  class  AuthServiceProvider  extends  ServiceProvider 

10  { 

11  /** 

12  * Perform  post-registration  booting  of  services. 

13  * 

14  * §return  void 

15  */ 

16  public  function  boot() 

17  { 

18  Auth : : provider( ' riak ' , function($app,  array  $config)  { 

19  //  Return  an  instance  of  1 1 luminate\Contracts\Auth\UserProvider . . . 

20  return  new  RiakUserProvider($app[ 'riak. connection  ]); 

21  }); 

22 


} 
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23 

24  /** 

25  * Register  bindings  in  the  container . 

26  * 

27  * §return  void 

28  */ 

29  public  function  register^) 

30  { 

31  // 

32  } 

33  } 


After  you  have  registered  the  provider  with  the  provider  method,  you  may  switch  to  the  new  user 
provider  in  your  conf  ig/auth . php  configuration  file.  First,  define  a provider  that  uses  your  new 
driver: 

1 'providers'  =>  [ 

'users'  =>  [ 

' driver ' =>  ' riak ' , 

4 ], 

5 ], 


Then,  you  may  use  this  provider  in  your  guards  configuration: 

1 'guards'  =>  [ 

2 'web'  =>  [ 

'driver'  =>  'session', 

4 'provider'  =>  'users', 

5 ], 

6 ], 


The  User  Provider  Contract 

The  1 1 luminate\Contracts\Auth\UserProvider  implementations  are  only  responsible  for  fetching 
a Illuminate\Contracts\Auth\Authenticatable  implementation  out  of  a persistent  storage  sys- 
tem, such  as  MySQL,  Riak,  etc.  These  two  interfaces  allow  the  Laravel  authentication  mechanisms 
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to  continue  functioning  regardless  of  how  the  user  data  is  stored  or  what  type  of  class  is  used  to 
represent  it. 

Let’s  take  a look  at  the  1 1 lumi nate \Contracts \Auth\User Provider  contract: 

1 < ?php 

2 

3 namespace  1 1 luminate\Contracts\Auth; 

4 

5 interface  UserProvider  { 

6 

7 public  function  retr ieveById($identi f ier ) ; 

8 public  function  retr ieveByToken($identi f ier , $token); 

public  function  updateRememberToken( Authenticatable  $user,  $token); 

10  public  function  retrieveByCredentials(array  $credentials) ; 

public  function  val idateCredentials( Authenticatable  $user,  array  $credential\ 

12  s); 

13 

14  } 


The  retrieveByld  function  typically  receives  a key  representing  the  user,  such  as  an  auto- 
incrementing ID  from  a MySQL  database.  The  Authenticatable  implementation  matching  the  ID 
should  be  retrieved  and  returned  by  the  method. 

The  retrieveByToken  function  retrieves  a user  by  their  unique  $identifier  and  “remember  me” 
$token,  stored  in  a field  remember_token.  As  with  the  previous  method,  the  Authenticatable 
implementation  should  be  returned. 

The  updateRememberToken  method  updates  the  $user  field  remember_token  with  the  new  $token. 
The  new  token  can  be  either  a fresh  token,  assigned  on  a successful  “remember  me”  login  attempt, 
or  a null  when  the  user  is  logged  out. 

The  retrieveByCredentials  method  receives  the  array  of  credentials  passed  to  the  Auth  : : attempt 
method  when  attempting  to  sign  into  an  application.  The  method  should  then  “query”  the  underlying 
persistent  storage  for  the  user  matching  those  credentials.  Typically,  this  method  will  run  a 
query  with  a “where”  condition  on  $credentials  ['  username '] . The  method  should  then  return 
an  implementation  of  User  Inter  face.  This  method  should  not  attempt  to  do  any  password 
validation  or  authentication. 

The  validateCredentials  method  should  compare  the  given  $user  with  the  $credentials  to 
authenticate  the  user.  For  example,  this  method  might  compare  the  $user->getAuthPassword( ) 
string  to  a Hash  : : make  of  $credentials  [ 1 password  1 ] . This  method  should  only  validate  the  user’s 
credentials  and  return  a boolean. 
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The  Authenticatable  Contract 

Now  that  we  have  explored  each  of  the  methods  on  the  UserProvider,  let’s  take  a look  at  the 
Authenticatable  contract.  Remember,  the  provider  should  return  implementations  of  this  interface 
from  the  retrieveByld  and  retrieveByCredentials  methods: 

1 < ?php 

2 

3 namespace  Illuminate \Contracts\Auth; 

4 

5 interface  Authenticatable  { 

6 

7 public  function  getAuthldenti f ier ( ) ; 

8 public  function  getAuthPassword( ) ; 

9 public  function  getRememberToken( ) ; 

10  public  function  setRememberToken($value) ; 

11  public  function  getRememberTokenName( ) ; 

12 

13  } 


This  interface  is  simple.  The  getAuthldenti f ier  method  should  return  the  “primary  key”  of 
the  user.  In  a MySQL  back-end,  again,  this  would  be  the  auto-incrementing  primary  key.  The 
getAuthPassword  should  return  the  user’s  hashed  password.  This  interface  allows  the  authentication 
system  to  work  with  any  User  class,  regardless  of  what  ORM  or  storage  abstraction  layer  you  are 
using.  By  default,  Laravel  includes  a User  class  in  the  app  directory  which  implements  this  interface, 
so  you  may  consult  this  class  for  an  implementation  example. 


Events 

Laravel  raises  a variety  of  events  during  the  authentication  process.  You  may  attach  listeners  to  these 
events  in  your  EventServiceProvider: 


1  /** 

2 * The  event  listener  mappings  for  the  application. 

3 * 

4 * §var  array 

5 V 

6 protected  Slisten  = [ 

7 ' 1 1 luminate\Auth\Events\Attempting ' =>  [ 

' App\Listeners\LogAuthenticationAttempt ' , 
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17 

18 

19 

20 
21 
22 


' II luminate\Auth\Events\Login ' =>  [ 

1 App\Listeners\LogSuccessfulLogin  1 


' II luminate\Auth\Events\Logout ' =>  [ 

' App\Listeners\LogSuccessful Logout 

], 


' II luminate\Auth\Events\Lockout ' =>  [ 
1 App\Listeners\LogLockout ' , 
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Introduction 

In  addition  to  providing  authentication  services  out  of  the  box,  Laravel  also  provides  a simple  way 
to  organize  authorization  logic  and  control  access  to  resources.  There  are  a variety  of  methods  and 
helpers  to  assist  you  in  organizing  your  authorization  logic,  and  we’ll  cover  each  of  them  in  this 
document. 

Defining  Abilities 


The  simplest  way  to  determine  if  a user  may  perform  a given  action  is  to  define  an  “ability”  using  the 
1 1 luminate\Auth\Access\Gate  class.  The  AuthServiceProvider  which  ships  with  Laravel  serves  as 
a convenient  location  to  define  all  of  the  abilities  for  your  application.  For  example,  let’s  define  an 
update- post  ability  which  receives  the  current  User  and  a Post  model.  Within  our  ability,  we  will 
determine  if  the  user’s  id  matches  the  post’s  user_id: 


1 < ?php 

2 

3 namespace  App\Providers; 

4 

5 use  1 1 luininate\Contracts\Auth\Access\Gate  as  GateContract; 

6 use  1 1 luminate\Foundation\Support\Providers\AuthServiceProvider  as  ServiceProvid\ 

7 er ; 

8 

9 class  AuthServiceProvider  extends  ServiceProvider 

10  { 

11  /** 

12  * Register  any  application  authentication  / authorization  services . 

13  * 

14  * §param  \Illuminate\Contracts\Auth\Access\Gate  $gate 
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15  * §return  void 

16  V 

17  public  function  boot(GateContract  $gate) 

18  { 

19  $this- > register Pol icies($gate) ; 

20 

21  $gate- >define( 1 update-post ' , function  ($user,  $post)  { 

return  $user->id  ===  $post->user_id; 

23  }); 

24  } 

25  } 


Note  that  we  did  not  check  if  the  given  $user  is  not  NULL.  The  Gate  will  automatically  return  false 
for  all  abilities  when  there  is  not  an  authenticated  user  or  a specific  user  has  not  been  specified 
using  the  forUser  method. 

Class  Based  Abilities 

In  addition  to  registering  Closures  as  authorization  callbacks,  you  may  register  class  methods  by 
passing  a string  containing  the  class  name  and  the  method.  When  needed,  the  class  will  be  resolved 
via  the  service  container: 


1 $gate- >define( ' update-post ' , 1 Class@method ' ) ; 


<a  name=”intercepting-all-checks”></a>  ####  Intercepting  Authorization  Checks  {#authorization- 
intercepting-authorization-checks} 

Sometimes,  you  may  wish  to  grant  all  abilities  to  a specific  user.  For  this  situation,  use  the  before 
method  to  define  a callback  that  is  run  before  all  other  authorization  checks: 

1 $gate->before( function  ($user,  $ability)  { 
if  ($user- > isSuperAdmin( ) ) { 
return  true; 

4 } 

5 }); 


If  the  before  callback  returns  a non-null  result  that  result  will  be  considered  the  result  of  the  check. 
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You  may  use  the  after  method  to  define  a callback  to  be  executed  after  every  authorization  check. 
However,  you  may  not  modify  the  result  of  the  authorization  check  from  an  a f ter  callback: 


1 $gate- >after( function  ($user,  $ability,  $result,  $arguments)  { 

2 // 

3 }); 


Checking  Abilities 

Via  The  Gate  Facade 

Once  an  ability  has  been  defined,  we  may  “check”  it  in  a variety  of  ways.  First,  we  may  use  the 
check,  allows,  or  denies  methods  on  the  Gate  facade.  All  of  these  methods  receive  the  name  of  the 
ability  and  the  arguments  that  should  be  passed  to  the  ability’s  callback.  You  do  not  need  to  pass 
the  current  user  to  these  methods,  since  the  Gate  will  automatically  prepend  the  current  user  to  the 
arguments  passed  to  the  callback.  So,  when  checking  the  update-post  ability  we  defined  earlier,  we 
only  need  to  pass  a Post  instance  to  the  denies  method: 


1 < ?php 

2 

3 namespace  App\Http\Control lers; 

4 

5 use  Gate; 

6 use  App\User; 

7 use  App\Post; 

8 use  App\Http\Controllers\Controller; 

9 

10  class  PostController  extends  Controller 

11  { 

12  /** 

13  * Update  the  given  post. 

14  * 

15  * §param  int  $id 

16  * @return  Response 

17  */ 

18  public  function  update($id) 

19  { 

20 
21 


$post  = Post: : findOrFail($id); 
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22 

23 

24 


if  (Gate :: denies( 1 2 3 update-post 1 , $post))  { 
abort(403) ; 


25 

26 

27  } 

28  } 


//  Update  Post.  . . 


Of  course,  the  allows  method  is  simply  the  inverse  of  the  denies  method,  and  returns  true  if  the 
action  is  authorized.  The  check  method  is  an  alias  of  the  allows  method. 

Checking  Abilities  For  Specific  Users 

If  you  would  like  to  use  the  Gate  facade  to  check  if  a user  other  than  the  currently  authenticated 
user  has  a given  ability,  you  may  use  the  forUser  method: 


1 if  (Gate :: forUser ($user) - >al lows( ' update-post ' , $post))  { 

2 // 

3 } 


Passing  Multiple  Arguments 

Of  course,  ability  callbacks  may  receive  multiple  arguments: 

1 Gate :: define( ' delete -comment 1 , function  ($user,  $post,  $comment)  { 

2 // 


If  your  ability  needs  multiple  arguments,  simply  pass  an  array  of  arguments  to  the  Gate  methods: 


1 if  (Gate :: al lows( ’ delete-comment 1 , [$post,  $comment]))  { 

2 // 

3 } 


3 }); 
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Via  The  User  Model 

Alternatively,  you  may  check  abilities  via  the  User  model  instance.  By  default,  Laravel’s  App\User 
model  uses  an  Author izable  trait  which  provides  two  methods:  can  and  cannot.  These  methods 


may  be  used  similarly  to  the  allows  and  denies  methods  present 
previous  example,  we  may  modify  our  code  like  so: 

on  the  Gate  facade.  So,  using  our 

1 

2 

<?php 

3 

4 

namespace  App\Http\Control lers; 

5 

use  App\Post; 

6 

use  1 1 luminate\Http\Request; 

7 

8 
9 

use  App\Http\Control lers\Control ler ; 

class  PostController  extends  Controller 

10 

{ 

11 

/** 

12 

* Update  the  gi ven  post . 

13 

* 

14 

* §param  \Illuminate\Http\Request  $request 

15 

* §param  int  $id 

16 

* §return  Response 

17 

*/ 

18 

public  function  update( Request  Irequest,  lid) 

19 

{ 

20 

Ipost  Post: : f indOrFa i 1 ( |id ) ; 

21 

22 

i f (Irequest- > user ( ) - > cannot ( 1 update -post ' , 

Ipost))  { 

23 

abort(403) ; 

24 

1 

25 

26 

//  Update  Post.  . . 

27 

1 

28 

1 

Of  course,  the  can  method  is  simply  the  inverse  of  the  cannot  method: 


1 if  (Irequest- >user( )- >can( ' update-post ' , $post))  { 
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//  Update  Post . . . 

3 } 


Within  Blade  Templates 

For  convenience,  Laravel  provides  the  ©can  Blade  directive  to  quickly  check  if  the  currently 
authenticated  user  has  a given  ability  For  example: 


1 <a  href="/post/{ { $post->id  }}">View  Post</a> 

2 

3 @can( 'update-post' , $post) 

<a  href="/post/{ { $post->id  }}/edit">Edit  Post</a> 

5 @endcan 


You  may  also  combine  the  @can  directive  with  ©else  directive: 


1 

@can( 'update-post' , $post) 

2 

<!--  The  Current  User 

Can 

Update  The  Post  --> 

3 

@else 

4 

<!--  The  Current  User 

Can 

t Update  The  Post  --> 

5 

@endcan 

Within  Form  Requests 

You  may  also  choose  to  utilize  your  Gate  defined  abilities  from  a form  request’s  authorize  method. 
For  example: 
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1 /** 

2 * Determine  if  the  user  is  authorized  to  make  this  request. 

3 * 

4 * §return  bool 

5 V 

6 public  function  authorize() 

7 { 

Spostld  = $this- >route( ' post ' ) ; 

9 

return  Gate  al lows( ' update ' , Post  : f indOrFai 1 (Spostld) ) ; 

11  } 


Policies 

Creating  Policies 

Since  defining  all  of  your  authorization  logic  in  the  AuthServiceProvider  could  become  cumber- 
some in  large  applications,  Laravel  allows  you  to  split  your  authorization  logic  into  “Policy”  classes. 
Policies  are  plain  PHP  classes  that  group  authorization  logic  based  on  the  resource  they  authorize. 

First,  let’s  generate  a policy  to  manage  authorization  for  our  Post  model.  You  may  generate  a policy 
using  the  make : pol  icy  artisan  command.  The  generated  policy  will  be  placed  in  the  app/Pol  icies 
directory: 


1 php  artisan  make: pol icy  PostPolicy 


Registering  Policies 

Once  the  policy  exists,  we  need  to  register  it  with  the  Gate  class.  The  AuthServ  i ceProv i der  contains 
a policies  property  which  maps  various  entities  to  the  policies  that  manage  them.  So,  we  will 
specify  that  the  Post  model’s  policy  is  the  PostPolicy  class: 
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1 < ?php 

2 

3 namespace  App\Providers; 

4 

5 use  App\Post; 

6 use  App\Pol icies\PostPol icy ; 

7 use  1 1 luminate\Foundation\Support\Providers\AuthServiceProvider  as  ServiceProvid\ 

8 er ; 

9 

10  class  AuthServiceProvider  extends  ServiceProvider 

11  { 

12  /** 

13  * The  policy  mappings  for  the  application. 

14  * 

15  * §var  array 

16  V 

17  protected  Spolicies  = [ 

18  Post::class  =>  PostPol icy :: class , 

19  ]; 

20 

21  /** 

* Register  any  application  authentication  / authorization  services . 

23  * 

24  * §param  \Illuminate\Contracts\Auth\Access\Gate  $gate 

25  * §return  void 

26  V 

27  public  function  boot(GateContract  $gate) 

28  { 

29  $this->registerPolicies($gate) ; 

30  } 

31  } 


Writing  Policies 

Once  the  policy  has  been  generated  and  registered,  we  can  add  methods  for  each  ability  it  authorizes. 
For  example,  let’s  define  an  update  method  on  our  PostPolicy,  which  will  determine  if  the  given 
User  can  “update”  a Post: 
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1 < ?php 

2 

3 namespace  App\Pol icies; 

4 

5 use  App\User; 

6 use  App\Post; 

7 

8 class  PostPolicy 

9 { 


10 

/** 

11 

* Determine  if  the  given  post  can  be  updated  by  the  user 

12 

* 

13 

* @param  \App\User  $user 

14 

* §param  \App\Post  $post 

15 

* §return  bool 

16 

*/ 

17 

public 

function  update(User  $user,  Post  $post) 

18 

{ 

19 

return  $user->id  ===  $post- >user_id; 

20 

} 

21 

} 

You  may  continue  to  define  additional  methods  on  the  policy  as  needed  for  the  various  abilities 
it  authorizes.  For  example,  you  might  define  show,  destroy,  or  addComment  methods  to  authorize 
various  Post  actions. 


Note:  All  policies  are  resolved  via  the  Laravel  service  container,  meaning  you  may  type- 
hint  any  needed  dependencies  in  the  policy’s  constructor  and  they  will  be  automatically 
injected. 


Intercepting  All  Checks 

Sometimes,  you  may  wish  to  grant  all  abilities  to  a specific  user  on  a policy.  For  this  situation,  define 
a before  method  on  the  policy.  This  method  will  be  run  before  all  other  authorization  checks  on  the 
policy: 
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1 public  function  before($user , $ability) 

2 { 

if  ($user->isSuperAdmin( ))  { 

4 return  true; 

5 } 

6 } 


If  the  before  method  returns  a non-null  result  that  result  will  be  considered  the  result  of  the  check. 

Checking  Policies 

Policy  methods  are  called  in  exactly  the  same  way  as  Closure  based  authorization  callbacks.  You 
may  use  the  Gate  facade,  the  User  model,  the  @can  Blade  directive,  or  the  policy  helper. 

Via  The  Gate  Facade 

The  Gate  will  automatically  determine  which  policy  to  use  by  examining  the  class  of  the  arguments 
passed  to  its  methods.  So,  if  we  pass  a Post  instance  to  the  denies  method,  the  Gate  will  utilize  the 
corresponding  PostPolicy  to  authorize  actions: 


1 < ?php 

2 

3 namespace  App\Http\Control lers; 

4 

5 use  Gate; 

6 use  App\User; 

7 use  App\Post; 

8 use  App\Http\Controllers\Controller; 

9 

10  class  PostController  extends  Controller 

11  { 

12  /** 

13  * Update  the  given  post. 

14  * 

15  * @param  int  $id 

16  * @return  Response 

17  */ 

18  public  function  update($id) 

19  { 

20 
21 


$post  = Post : : f indOrFai 1 ($id) ; 
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22 

23 

24 


if  (Gate :: denies( 1 update ' , $post))  { 
abort(403) ; 


25 

26 

27  } 

28  } 


//  Update  Post.  . . 


Via  The  User  Model 

The  User  model’s  can  and  cannot  methods  will  also  automatically  utilize  policies  when  they  are 
available  for  the  given  arguments.  These  methods  provide  a convenient  way  to  authorize  actions  for 
any  User  instance  retrieved  by  your  application: 

1 if  ($user- >can( ' update ' , $post))  { 

2 // 

3 } 

4 

5 if  ($user- >cannot( 1 update ' , $post))  { 

6 // 

7 } 


Within  Blade  Templates 

Likewise,  the  @can  Blade  directive  will  utilize  policies  when  they  are  available  for  the  given 
arguments: 


1 @can( ' update ' , $post) 

<!--  The  Current  User  Can  Update  The  Post  --> 

3 §endcan 


Via  The  Policy  Helper 

The  global  policy  helper  function  may  be  used  to  retrieve  the  Policy  class  for  a given  class 
instance.  For  example,  we  may  pass  a Post  instance  to  the  policy  helper  to  get  an  instance  of  our 
corresponding  PostPolicy  class: 
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1 

2 

3 

if  (policy($post)->update($user,  $post))  { 
// 

} 

Controller  Authorization 

By  default,  the  base  App\Http\Controllers\Controller  class  included  with  Laravel  uses  the 
Author izesRequests  trait.  This  trait  provides  the  authorize  method,  which  may  be  used  to  quickly 
authorize  a given  action  and  throw  a HttpException  if  the  action  is  not  authorized. 

The  authorize  method  shares  the  same  signature  as  the  various  other  authorization  methods  such  as 
Gate:  : al  lows  and  $user->can( ).  So,  let’s  use  the  authorize  method  to  quickly  authorize  a request 
to  update  a Post: 

1 

2 

<?php 

3 

4 

namespace  App\Http\Control lers; 

5 

use  App\Post; 

6 

use  App\Http\Control lers\Control ler ; 

8 

class  PostController  extends  Controller 

9 

{ 

10 

/** 

11 

* Update  the  given  post. 

12 

* 

13 

* § par am  int  $id 

14 

* @return  Response 

15 

*/ 

16 

public  function  update($id) 

17 

{ 

18 

$post  = Post: : f indOrFa i 1 ($id ) ; 

19 

20 

$th is  - > author ize( 1 update ' , $post) ; 

21 

22 

//  Update  Post.  . . 

23 

1 

24 

} 
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If  the  action  is  authorized,  the  controller  will  continue  executing  normally;  however,  if  the  author  i ze 
method  determines  that  the  action  is  not  authorized,  a HttpException  will  automatically  be  thrown 
which  generates  a HTTP  response  with  a 403  Not  Authorized  status  code.  As  you  can  see,  the 
authorize  method  is  a convenient,  fast  way  to  authorize  an  action  or  throw  an  exception  with  a 
single  line  of  code. 

The  Author izesRequests  trait  also  provides  the  authorizeForUser  method  to  authorize  an  action 
on  a user  that  is  not  the  currently  authenticated  user: 


1  $this->authorizeForUser($user,  'update',  $post); 


Automatically  Determining  Policy  Methods 

Frequently,  a policy’s  methods  will  correspond  to  the  methods  on  a controller.  For  example,  in  the 
update  method  above,  the  controller  method  and  the  policy  method  share  the  same  name:  update. 

For  this  reason,  Laravel  allows  you  to  simply  pass  the  instance  arguments  to  the  authorize  method, 
and  the  ability  being  authorized  will  automatically  be  determined  based  on  the  name  of  the  calling 
function.  In  this  example,  since  authorize  is  called  from  the  controller’s  update  method,  the  update 
method  will  also  be  called  on  the  PostPolicy: 


1 /** 

2 * Update  the  given  post. 

3 * 

4 * @param  int  $id 

5 * §return  Response 

6 V 

7 public  function  update($id) 

8 { 

$post  = Post  : f indOrFai 1 (Sid) ; 

10 

$this- > author ize($post) ; 

12 

13  //  Update  Post. . . 

14  } 
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Introduction 

Artisan  is  the  name  of  the  command-line  interface  included  with  Laravel.  It  provides  a number 
of  helpful  commands  for  your  use  while  developing  your  application.  It  is  driven  by  the  powerful 
Symfony  Console  component.  To  view  a list  of  all  available  Artisan  commands,  you  may  use  the 
list  command: 

1 php  artisan  list 


Every  command  also  includes  a “help”  screen  which  displays  and  describes  the  command’s  available 
arguments  and  options.  To  view  a help  screen,  simply  precede  the  name  of  the  command  with  help: 

1 php  artisan  help  migrate 


Writing  Commands 

In  addition  to  the  commands  provided  with  Artisan,  you  may  also  build  your  own  custom 
commands  for  working  with  your  application.  You  may  store  your  custom  commands  in  the 
app/Consol e/Commands  directory;  however,  you  are  free  to  choose  your  own  storage  location  as 
long  as  your  commands  can  be  autoloaded  based  on  your  composer . json  settings. 

To  create  a new  command,  you  may  use  the  make: console  Artisan  command,  which  will  generate 
a command  stub  to  help  you  get  started: 
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1 php  artisan  make: console  SendEmails 


The  command  above  would  generate  a class  at  app/Console/Commands/SendEmails.php.  When 
creating  the  command,  the  - -command  option  may  be  used  to  assign  the  terminal  command  name: 


1 php  artisan  make: console  SendEmails  - -command=emai Is : send 


Command  Structure 

Once  your  command  is  generated,  you  should  fill  out  the  signature  and  description  properties  of 
the  class,  which  will  be  used  when  displaying  your  command  on  the  1 ist  screen. 

The  handle  method  will  be  called  when  your  command  is  executed.  You  may  place  any  command 
logic  in  this  method.  Let’s  take  a look  at  an  example  command. 

Note  that  we  are  able  to  inject  any  dependencies  we  need  into  the  command’s  constructor.  The 
Laravel  service  container  will  automatically  inject  all  dependencies  type-hinted  in  the  constructor. 
For  greater  code  reusability,  it  is  good  practice  to  keep  your  console  commands  light  and  let  them 
defer  to  application  services  to  accomplish  their  tasks. 


1 < ?php 

2 

3 namespace  App\Console\Commands; 

4 

5 use  App\User; 

6 use  App\DripEmai ler ; 

7 use  1 1 luminate\Console\Command; 

8 

9 class  SendEmails  extends  Command 

10  { 

11  /** 

12  * The  name  and  signature  of  the  console  command. 

13  * 

14  * @var  string 

15  V 

16  protected  Ssignature  = 'email: send  {user}'; 

17 

18  /** 

19  * The  console  command  description . 
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20  * 

21  * §var  string 

22  */ 

protected  $description  = 'Send  drip  e-mails  to  a user'; 

24 

25  /** 

26  * The  drip  e-mail  service. 

27  * 

28  * §var  DripEmailer 

29  */ 

30  protected  $drip; 

31 

32  /** 

33  * Create  a new  command  instance. 

34  * 

35  * @param  DripEmailer  $drip 

36  * §return  void 

37  V 

public  function  construct(DripEmai ler  $drip) 

39  { 

40  parent:: constructQ; 

41 

42  $this->drip  = $drip; 

43  } 

44 

45  /** 

46  * Execute  the  console  command. 

47  * 

48  * §return  mixed 

49  */ 

50  public  function  handle() 

51  { 

52  $this- >dr ip->send(User : : f ind($th is- > argument ( ' user  ' ) ) ) ; 

53 

54 


} 


} 
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Command  I/O 

Defining  Input  Expectations 

When  writing  console  commands,  it  is  common  to  gather  input  from  the  user  through  arguments 
or  options.  Laravel  makes  it  very  convenient  to  define  the  input  you  expect  from  the  user  using  the 
signature  property  on  your  commands.  The  signature  property  allows  you  to  define  the  name, 
arguments,  and  options  for  the  command  in  a single,  expressive,  route-like  syntax. 

All  user  supplied  arguments  and  options  are  wrapped  in  curly  braces.  In  the  following  example,  the 
command  defines  one  required  argument:  user: 


1 /** 

2 * The  name  and  signature  of  the  console  command. 

3 * 

4 * §var  string 

5 V 

6 protected  $signature  = 'email :send  {user}'; 


You  may  also  make  arguments  optional  and  define  default  values  for  optional  arguments: 

1 //  Optional  argument... 

2 email :send  {user?} 

3 

4 //  Optional  argument  with  default  value... 

5 email: send  {user=foo} 


Options,  like  arguments,  are  also  a form  of  user  input.  However,  they  are  prefixed  by  two  hyphens 
(-  -)  when  they  are  specified  on  the  command  line.  We  can  define  options  in  the  signature  like  so: 


1 /** 

2 * The  name  and  signature  of  the  console  command. 

3 * 

4 * §var  string 

5 */ 

6 protected  $signature  = 'email : send  {user}  {--queue}'; 
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In  this  example,  the  - -queue  switch  may  be  specified  when  calling  the  Artisan  command.  If  the 
- - queue  switch  is  passed,  the  value  of  the  option  will  be  true.  Otherwise,  the  value  will  be  false: 


1 php  artisan  email: send  1 --queue 


You  may  also  specify  that  the  option  should  be  assigned  a value  by  the  user  by  suffixing  the  option 
name  with  a = sign,  indicating  that  a value  should  be  provided: 


1 /** 

2 * The  name  and  signature  of  the  console  command. 

3 * 

4 * §var  string 

5 */ 

6 protected  $signature  = 'email : send  {user}  {--queue=}'; 


In  this  example,  the  user  may  pass  a value  for  the  option  like  so: 
1 php  artisan  email: send  1 - -queue=default 


You  may  also  assign  default  values  to  options: 
1 email :send  {user}  { - -queue=default} 


To  assign  a shortcut  when  defining  an  option,  you  may  specify  it  before  the  option  name  and  use  a 
| delimiter  to  separate  the  shortcut  from  the  full  option  name: 


1 email :send  {user}  {--Qlqueue} 


If  you  would  like  to  define  arguments  or  options  to  expect  array  inputs,  you  may  use  the  * character: 
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1 email: send  {user*} 

2 

3 email :send  {user}  {--id=*} 


Input  Descriptions 

You  may  assign  descriptions  to  input  arguments  and  options  by  separating  the  parameter  from  the 
description  using  a colon: 

1 /** 

2 * The  name  and  signature  of  the  console  command. 

3 * 

4 * §var  string 

5 V 

6 protected  Ssignature  = 'email :send 

{user  : The  ID  of  the  user} 

{--queue=  : Whether  the  job  should  be  queued}'; 


Retrieving  Input 

While  your  command  is  executing,  you  will  obviously  need  to  access  the  values  for  the  arguments 
and  options  accepted  by  your  command.  To  do  so,  you  may  use  the  argument  and  option  methods: 

1 /** 

2 * Execute  the  console  command. 

3 * 

4 * §return  mixed 

5 V 

6 public  function  handle() 

7 { 

$userld  = $this- >argument( 1 user ’ ) ; 

9 

10  // 

11  } 


If  you  need  to  retrieve  all  of  the  arguments  as  an  array,  call  argument  with  no  parameters: 
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1 $arguments  = $this- >argument( ) ; 


Options  may  be  retrieved  just  as  easily  as  arguments  using  the  option  method.  Like  the  argument 
method,  you  may  call  option  without  any  parameters  in  order  to  retrieve  all  of  the  options  as  an 
array: 

1 //  Retrieve  a specific  option... 

2 IqueueName  = $this->option( ' queue ') ; 

3 

4 //  Retrieve  all  options... 

5 $options  = $this->option( ) ; 


If  the  argument  or  option  does  not  exist,  null  will  be  returned. 

Prompting  For  Input 

In  addition  to  displaying  output,  you  may  also  ask  the  user  to  provide  input  during  the  execution  of 
your  command.  The  ask  method  will  prompt  the  user  with  the  given  question,  accept  their  input, 
and  then  return  the  user’s  input  back  to  your  command: 


1 /** 

2 * Execute  the  console  command. 

3 * 

4 * §return  mixed 

5 V 

6 public  function  handle() 

7 { 

$name  = $this- >ask( 'What  is  your  name?'); 

9 } 


The  secret  method  is  similar  to  ask,  but  the  user’s  input  will  not  be  visible  to  them  as  they  type  in 
the  console.  This  method  is  useful  when  asking  for  sensitive  information  such  as  a password: 


1 $password  = $this- >secret( 'What  is  the  password?'); 
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Asking  For  Confirmation 

If  you  need  to  ask  the  user  for  a simple  confirmation,  you  may  use  the  confirm  method.  By  default, 
this  method  will  return  false.  However,  if  the  user  enters  y in  response  to  the  prompt,  the  method 
will  return  true. 


1 if  ($this- >conf irm( 1 Do  you  wish  to  continue?  [y I N ] ' ) ) { 

2 // 

3 } 


Giving  The  User  A Choice 

The  anticipate  method  can  be  used  to  provide  autocompletion  for  possible  choices.  The  user  can 
still  choose  any  answer,  regardless  of  the  auto-completion  hints: 

1 $name  = $this- >anticipate( 'What  is  your  name?',  ['Taylor',  'Dayle']); 


If  you  need  to  give  the  user  a predefined  set  of  choices,  you  may  use  the  choice  method.  The  user 
chooses  the  index  of  the  answer,  but  the  value  of  the  answer  will  be  returned  to  you.  You  may  set 
the  default  value  to  be  returned  if  nothing  is  chosen: 


1 $name  = $this- >choice( ' What  is  your  name?',  ['Taylor',  'Dayle'],  $default); 


Writing  Output 

To  send  output  to  the  console,  use  the  line,  info,  comment,  question  and  error  methods.  Each  of 
these  methods  will  use  the  appropriate  ANSI  colors  for  their  purpose. 

To  display  an  information  message  to  the  user,  use  the  info  method.  Typically,  this  will  display  in 
the  console  as  green  text: 
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1 /** 

2 * Execute  the  console  command. 

3 * 

4 * §return  mixed 

5 V 

6 public  function  handle() 

7 { 

$this- > info( ' Display  this  on  the  screen'); 

9 } 


To  display  an  error  message,  use  the  error  method.  Error  message  text  is  typically  displayed  in  red: 


1 $this- >error( ' Something  went  wrong!'); 


If  you  want  to  display  plain  console  output,  use  the  line  method.  The  line  method  does  not  receive 
any  unique  coloration: 


1 $this-> 1 ine( ' Display  this  on  the  screen'); 


Table  Layouts 

The  table  method  makes  it  easy  to  correctly  format  multiple  rows  / columns  of  data.  Just  pass  in 
the  headers  and  rows  to  the  method.  The  width  and  height  will  be  dynamically  calculated  based  on 
the  given  data: 


1 

$headers  = /"'Name',  'Email 'J; 

2 

3 

$users  = App\User : : al 1 ( [ ' name ' , 

' ema i 1 ' ] ) - > toArray ( ) ; 

4 

5 

$this->table($headers,  $users); 

Progress  Bars 

For  long  running  tasks,  it  could  be  helpful  to  show  a progress  indicator.  Using  the  output  object,  we 
can  start,  advance  and  stop  the  Progress  Bar.  You  have  to  define  the  number  of  steps  when  you  start 
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the  progress,  then  advance  the  Progress  Bar  after  each  step: 


1 $users  = App\User : : al 1 ( ) ; 

2 

3 $bar  = $this- >output- >createProgressBar(count($users) ) ; 

4 

5 foreach  ($users  as  $user)  { 

6 $this->performTask($user) ; 

7 

$bar- >advance( ) ; 

9 } 

10 

11  $bar- > f inish( ) ; 


For  more  advanced  options,  check  out  the  Symfony  Progress  Bar  component  documentation137. 

Registering  Commands 

Once  your  command  is  finished,  you  need  to  register  it  with  Artisan  so  it  will  be  available  for  use. 
This  is  done  within  the  app/Console/Kernel . php  file. 

Within  this  file,  you  will  find  a list  of  commands  in  the  commands  property.  To  register  your 
command,  simply  add  the  class  name  to  the  list.  When  Artisan  boots,  all  the  commands  listed  in 
this  property  will  be  resolved  by  the  service  container  and  registered  with  Artisan: 

1 protected  Scommands  = [ 

Commands \SendEmai Is : : class 

3 ]; 


Calling  Commands  Via  Code 

Sometimes  you  may  wish  to  execute  an  Artisan  command  outside  of  the  CLI.  For  example,  you 
may  wish  to  fire  an  Artisan  command  from  a route  or  controller.  You  may  use  the  call  method  on 
the  Artisan  facade  to  accomplish  this.  The  call  method  accepts  the  name  of  the  command  as  the 
first  argument,  and  an  array  of  command  parameters  as  the  second  argument.  The  exit  code  will  be 
returned: 

137http://symfony.com/  doc/2. 7/components/console/helpers/progressbar.html 
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1 

Route :: get( ' /foo ' , function  () 

{ 

2 

$exitCode  = Artisan :: cal  1 ( 

emai 1 : send ' , [ 

3 

' user ' =>  1 , ' - -queue ' 

=>  'default' 

4 

]); 

5 

6 

// 

7 

}); 

Using  the  queue  method  on  the  Artisan  facade,  you  may  even  queue  Artisan  commands  so  they  are 
processed  in  the  background  by  your  queue  workers: 

1 Route :: get( ' /foo ' , function  ()  { 

Artisan :: queue( 1 emai 1 : send  1 , [ 

'user'  =>  1,  '--queue'  =>  'default' 

4 ]); 

5 

6 // 

7 }); 


If  you  need  to  specify  the  value  of  an  option  that  does  not  accept  string  values,  such  as  the  - - force 
flag  on  the  migrate : refresh  command,  you  may  pass  a boolean  true  or  false: 


1 SexitCode  = Artisan :: cal  1 (' migrate : refresh ' , [ 
'--force'  =>  true, 

3 ]); 


Calling  Commands  From  Other  Commands 

Sometimes  you  may  wish  to  call  other  commands  from  an  existing  Artisan  command.  You  may  do 
so  using  the  call  method.  This  call  method  accepts  the  command  name  and  an  array  of  command 
parameters: 
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1 

2 

3 

4 

5 

6 

7 

8 
9 

10 

11 

12 

13 


/** 

* Execute  the  console  command. 

* 

* §return  mixed 

V 

public  function  handle() 

{ 

$this->call( 'email : send ' , [ 

'user'  =>  1,  '--queue'  =>  'default' 

]); 


} 


// 


If  you  would  like  to  call  another  console  command  and  suppress  all  of  its  output,  you  may  use  the 
callSilent  method.  The  ca  1 1 S i 1 ent  method  has  the  same  signature  as  the  call  method: 

1 $this->cal ISi lent( ' emai 1 : send ' , [ 

'user'  =>  1,  '--queue'  =>  'default' 

3 ]); 
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Introduction 

Laravel  Cashier  provides  an  expressive,  fluent  interface  to  Stripe’s138  subscription  billing  services.  It 
handles  almost  all  of  the  boilerplate  subscription  billing  code  you  are  dreading  writing.  In  addition 
to  basic  subscription  management,  Cashier  can  handle  coupons,  swapping  subscription,  subscription 
“quantities”,  cancellation  grace  periods,  and  even  generate  invoice  PDFs. 

Configuration 

Composer 

First,  add  the  Cashier  package  to  your  composer . json  file  and  run  the  composer  update  command: 


1 " laravel/cashier " : "~6.0" 


Service  Provider 

Next,  register  the  Laravel\Cashier\CashierServiceProvider  service  provider  in  your  app  config- 
uration file. 

Migration 

Before  using  Cashier,  we’ll  need  to  prepare  the  database.  We  need  to  add  several  columns  to  your 
users  table  and  create  a new  subscriptions  table  to  hold  all  of  our  customer’s  subscriptions: 


138https://stripe.com 
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1 

Schema :: table( ' users ' , function  (Stable)  { 

2 

Stable- > string ( ' str ipe_id ' )->nullable(); 

3 

Stable- > string ( ' card_brand ' )->nullable(); 

4 

Stable- > str ing( 1 card_last_four ' )->nullable(); 

5 

6 

}); 

7 

Schema :: create( ' subscriptions ' , function  (Stable)  { 

8 

Stable- > increments ( 'id'); 

9 

Stable- > integer( ' user_id ' ) ; 

10 

Stable- > str ing( ' name ' ) ; 

11 

Stable- > str ing( ' str ipe_id ' ) ; 

12 

Stable- > str ing( 1 str ipe_plan ' ) ; 

13 

Stable- > integer ( ' quantity ' ) ; 

14 

Stable- >timestamp( ' tr ial_ends_at ' )->nullable( ); 

15 

Stable- >timestamp( ' ends_at ' )->nullable(); 

16 

Stable- >timestamps( ) ; 

17 

}); 

Once  the  migrations  have  been  created,  simply  run  the  migrate  command. 


Model  Setup 

Next,  add  the  Billable  trait  to  your  model  definition: 

1 use  Laravel\Cashier\Billable; 

2 

3 class  User  extends  Authenticatable 

4 { 

5 use  Billable; 

6 } 


Stripe  Key 

Finally,  set  your  Stripe  key  in  your  services . php  configuration  file: 
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1 'stripe'  =>  [ 

'model'  =>  App\User :: class, 

'secret'  =>  env( ' STRIPE_API_SECRET ' ) , 

4 ], 


Subscriptions 

Creating  Subscriptions 

To  create  a subscription,  first  retrieve  an  instance  of  your  billable  model,  which  typically  will 
be  an  instance  of  App\User.  Once  you  have  retrieved  the  model  instance,  you  may  use  the 
newSubscription  method  to  create  the  model’s  subscription: 


1 $user  = User : : f ind(l ) ; 

2 

3 $user -> newSubscri.pt ion ( ' main ' , ' monthly ' ) - > create (ScreditCardToken) ; 


The  first  argument  passed  to  the  newSubscription  method  should  be  the  name  of  the  subscription. 
If  your  application  only  offers  a single  subscription,  you  might  call  this  main  or  primary.  The  second 
argument  is  the  specific  Stripe  plan  the  user  is  subscribing  to.  This  value  should  correspond  to  the 
plan’s  identifier  in  Stripe. 

The  create  method  will  automatically  create  the  Stripe  subscription,  as  well  as  update  your  database 
with  Stripe  customer  ID  and  other  relevant  billing  information.  If  your  plan  has  a trial  configured 
in  Stripe,  the  trial  end  date  will  also  automatically  be  set  on  the  user  record. 

Additional  User  Details 

If  you  would  like  to  specify  additional  customer  details,  you  may  do  so  by  passing  them  as  the  second 
argument  to  the  create  method: 

1 $user->newSubscription( ' main ' , 'monthly ' )->create($creditCardToken,  [ 

'email'  =>  $email,  'description'  =>  'Our  First  Customer' 

3 1); 
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To  learn  more  about  the  additional  fields  supported  by  Stripe,  check  out  Stripe’s  documentation  on 
customer  creation139. 


Coupons 

If  you  would  like  to  apply  a coupon  when  creating  the  subscription,  you  may  use  the  withCoupon 
method: 


1  $user->newSubscription( 'main' , 'monthly') 
- >withCoupon( 'code' ) 
->create($creditCardToken) ; 


Checking  Subscription  Status 

Once  a user  is  subscribed  to  your  application,  you  may  easily  check  their  subscription  status  using  a 
variety  of  convenient  methods.  First,  the  subscribed  method  returns  true  if  the  user  has  an  active 
subscription,  even  if  the  subscription  is  currently  within  its  trial  period: 


1 if  ($user- >subscr ibed( ' main ' ) ) { 

2 // 

3 } 


The  subscribed  method  also  makes  a great  candidate  for  a route  middleware,  allowing  you  to  filter 
access  to  routes  and  controllers  based  on  the  user’s  subscription  status: 


1 public  function  handle($request,  Closure  $next) 

2 { 

if  ($request->user( ) &&  ! $request- >user( ) - >subscribed( ' main ' ) ) { 

4 //  This  user  is  not  a paying  customer... 

5 return  redirect( ' bi 1 1 ing ' ) ; 

6 } 

7 

return  $next($request) ; 

9 } 


139https://stripe.com/docs/api#create_customer 
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If  you  would  like  to  determine  if  a user  is  still  within  their  trial  period,  you  may  use  the  onTrial 
method.  This  method  can  be  useful  for  displaying  a warning  to  the  user  that  they  are  still  on  their 
trial  period: 


1 if  ($user- >subscr iption( ' main *  1 2 3 ) - >onTr ial ( ) ) { 

2 // 

3 } 


The  onPlan  method  may  be  used  to  determine  if  the  user  is  subscribed  to  a given  plan  based  on  its 
Stripe  ID: 


1 if  ($user- >onPlan( 1 monthly 1 ) ) { 

2 // 

3 } 


Cancelled  Subscription  Status 

To  determine  if  the  user  was  once  an  active  subscriber,  but  has  cancelled  their  subscription,  you  may 
use  the  cancelled  method: 

1 if  ($user- >subscr iption( 1 main ' ) - >cancel led( ) ) { 

2 // 

3 } 


You  may  also  determine  if  a user  has  cancelled  their  subscription,  but  are  still  on  their  “grace  period” 
until  the  subscription  fully  expires.  For  example,  if  a user  cancels  a subscription  on  March  5th  that 
was  originally  scheduled  to  expire  on  March  10th,  the  user  is  on  their  “grace  period”  until  March 
10th.  Note  that  the  subscribed  method  still  returns  true  during  this  time. 

1 if  ($user- >subscr iption( ' main ' ) - >onGracePeriod( ) ) { 

2 // 

3 } 
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Changing  Plans 

After  a user  is  subscribed  to  your  application,  they  may  occasionally  want  to  change  to  a new 
subscription  plan.  To  swap  a user  to  a new  subscription,  use  the  swap  method.  For  example,  we  may 
easily  switch  a user  to  the  premium  subscription: 


1 $user  = App\User : : f ind(l ) ; 

2 

3 $user->subscription( 'main' )->swap( ' stripe-plan- id ' ); 


If  the  user  is  on  trial,  the  trial  period  will  be  maintained.  Also,  if  a “quantity”  exists  for  the 
subscription,  that  quantity  will  also  be  maintained.  If  you  would  like  to  invoice  the  customer 
immediately  after  swapping  plans,  use  the  invoice  method: 

1 $user- > subscription! ' main ' ) - >swap( ' stripe-plan- id ' ) ; 

2 

3 $user-> invoice! ) ; 


Subscription  Quantity 


Sometimes  subscriptions  are  affected  by  “quantity”.  For  example,  your  application  might  charge  $10 
per  month  per  user  on  an  account.  To  easily  increment  or  decrement  your  subscription  quantity, 
use  the  incrementQuantity  and  decrementQuantity  methods: 


1 $user  = User : : f ind(l ) ; 

2 

3 $user- > subscription! ' main ' ) -> incrementQuantity! ) ) 

4 

5 //  Add  five  to  the  subscription's  current  quantity... 

6 $user- >subscr iption( 'main' ) - > incrementQuantity(5) ; 

7 

8 $user- >subscr iption( 'main' ) ->decrementQuantity( ); 

9 

10  //  Subtract  five  to  the  subscription's  current  quantity... 

11  $user- Subscription! 'main' ) ->decrementQuantity(5) ; 


Alternatively,  you  may  set  a specific  quantity  using  the  updateQuantity  method: 
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1  $user->subscr iption( ' main ' ) - >updateQuantity(10) ; 


For  more  information  on  subscription  quantities,  consult  the  Stripe  documentation140. 

Subscription  Taxes 

With  Cashier,  it’s  easy  to  provide  the  tax_percent  value  sent  to  Stripe.  To  specify  the  tax  percentage 
a user  pays  on  a subscription,  implement  the  taxPercentage  method  on  your  billable  model,  and 
return  a numeric  value  between  0 and  100,  with  no  more  than  2 decimal  places. 


1 public  function  taxPercentage( ) { 

2 return  20; 

3 } 


This  enables  you  to  apply  a tax  rate  on  a model-by-model  basis,  which  may  be  helpful  for  a user 
base  that  spans  multiple  countries. 

Cancelling  Subscriptions 

To  cancel  a subscription,  simply  call  the  cancel  method  on  the  user’s  subscription: 


1 $user->subscription( ' main ' ) -> cancel ( ) ; 


When  a subscription  is  cancelled,  Cashier  will  automatically  set  the  ends_at  column  in  your 
database.  This  column  is  used  to  know  when  the  subscribed  method  should  begin  returning  false. 
For  example,  if  a customer  cancels  a subscription  on  March  1st,  but  the  subscription  was  not 
scheduled  to  end  until  March  5th,  the  subscribed  method  will  continue  to  return  true  until  March 
5th. 

You  may  determine  if  a user  has  cancelled  their  subscription  but  are  still  on  their  “grace  period” 
using  the  onGracePeriod  method: 


140 


https://stripe.eom/docs/guides/subscriptions#setting-quantities 
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1 if  ($user- >subscr iption( ' main  1 ) - >onGracePeriod( ) ) { 

2 // 

3 } 


Resuming  Subscriptions 

If  a user  has  cancelled  their  subscription  and  you  wish  to  resume  it,  use  the  resume  method.  The 
user  must  still  be  on  their  grace  period  in  order  to  resume  a subscription: 


1 $user-> subscription! ' main ' ) - > resume! ) ; 


If  the  user  cancels  a subscription  and  then  resumes  that  subscription  before  the  subscription  has  fully 
expired,  they  will  not  be  billed  immediately.  Instead,  their  subscription  will  simply  be  re-activated, 
and  they  will  be  billed  on  the  original  billing  cycle. 

Handling  Stripe  Webhooks 

Failed  Subscriptions 

What  if  a customer’s  credit  card  expires?  No  worries  - Cashier  includes  a Webhook  controller  that 
can  easily  cancel  the  customer’s  subscription  for  you.  Just  point  a route  to  the  controller: 


1 Route:: post( 

' stripe/webhook ' , 

' \Laravel \Cashier\Http\Control lers\WebhookControl ler@handleWebhook 1 

4 ); 


That’s  it!  Failed  payments  will  be  captured  and  handled  by  the  controller.  The  controller  will  cancel 
the  customer’s  subscription  when  Stripe  determines  the  subscription  has  failed  (normally  after  three 
failed  payment  attempts).  Don’t  forget:  you  will  need  to  configure  the  webhook  URI  in  your  Stripe 
control  panel  settings. 

Since  Stripe  webhooks  need  to  bypass  Laravel’s  CSRF  verification,  be  sure  to  list  the  URI  as  an 
exception  in  your  Ver  i fyCsrf Token  middleware: 
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1 protected  Sexcept  = [ 
' stripe/* ' , 

3 ]; 


Other  Webhooks 

If  you  have  additional  Stripe  webhook  events  you  would  like  to  handle,  simply  extend  the  Webhook 
controller.  Your  method  names  should  correspond  to  Cashier’s  expected  convention,  specifically, 
methods  should  be  prefixed  with  handle  and  the  “camel  case”  name  of  the  Stripe  webhook  you 
wish  to  handle.  For  example,  if  you  wish  to  handle  the  invoice . payment_succeeded  webhook,  you 
should  add  a handlelnvoicePaymentSucceeded  method  to  the  controller. 


1 < ?php 

2 

3 namespace  App\Http\Control lers; 

4 

5 use  Laravel\Cashier\Http\Controllers\WebhookController  as  BaseControl ler ; 

6 

7 class  WebhookControl ler  extends  BaseControl ler 

8 { 

g /** 

10  * Handle  a stripe  webhook. 

11  * 

12  * §param  array  $payload 

13  * §return  Response 

14  */ 

15  public  function  handleInvoicePaymentSucceeded($payload) 

16  { 

17  //  Handle  The  Event 

18  } 

19  } 


Single  Charges 


If  you  would  like  to  make  a “one  off”  charge  against  a subscribed  customer’s  credit  card,  you  may 
use  the  charge  method  on  a billable  model  instance.  The  charge  method  accepts  the  amount  you 
would  like  to  charge  in  the  lowest  denominator  of  the  currency  used  by  your  application.  So, 
for  example,  the  example  below  will  charge  100  cents,  or  $1.00,  against  the  user’s  credit  card: 
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1 $user->charge(100) ; 


The  charge  method  accepts  an  array  as  its  second  argument,  allowing  you  to  pass  any  options  you 
wish  to  the  underlying  Stripe  charge  creation: 

1 $user- >charge(100,  [ 

'source'  =>  $token, 

' receipt_emai 1 ' =>  $user- >emai 1 , 

4 ]); 


The  charge  method  will  return  false  if  the  charge  fails.  This  typically  indicates  the  charge  was 
denied: 


1 if  ( ! $user->charge(100) ) { 

//  The  charge  was  denied. . . 

3 } 


If  the  charge  is  successful,  the  full  Stripe  response  will  be  returned  from  the  method. 


Invoices 

You  may  easily  retrieve  an  array  of  a billable  model’s  invoices  using  the  invoices  method: 
1 Sinvoices  = $user- > invoices( ) ; 


When  listing  the  invoices  for  the  customer,  you  may  use  the  invoice’s  helper  methods  to  display  the 
relevant  invoice  information.  For  example,  you  may  wish  to  list  every  invoice  in  a table,  allowing 
the  user  to  easily  download  any  of  them: 
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1 <table> 

@foreach  ($invoices  as  $invoice) 

3 <tr> 

4 <td>{{  $invoice- >date( ) - >toFormattedDateString( ) }}</td> 

5 <td>{{  $invoice- >total ( ) }}</td> 

<td><a  href="/user/invoice/{ { $invoice->id  }}">Download</a> </td> 
7 </tr> 

@endforeach 
9 </table> 


Generating  Invoice  PDFs 

Before  generating  invoice  PDFs,  you  need  to  install  the  dompdf  PHP  library: 

1 composer  require  dompdf/dompdf 


From  within  a route  or  controller,  use  the  down  load  Invoice  method  to  generate  a PDF  download 
of  the  invoice.  This  method  will  automatically  generate  the  proper  HTTP  response  to  send  the 
download  to  the  browser: 


1 Route :: get( ' user/invoice/{ invoice} ' , function  ($invoiceId)  { 
return  Auth : : user( ) - >downloadInvoice($invoiceId,  [ 
'vendor'  =>  'Your  Company', 

4 'product'  =>  'Your  Product', 

5 ]); 

6 }); 
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Configuration 

Laravel  provides  a unified  API  for  various  caching  systems.  The  cache  configuration  is  located  at 
conf  ig/cache . php.  In  this  file  you  may  specify  which  cache  driver  you  would  like  used  by  default 
throughout  your  application.  Laravel  supports  popular  caching  backends  like  Memcached141  and 
Redis142  out  of  the  box. 

The  cache  configuration  file  also  contains  various  other  options,  which  are  documented  within 
the  file,  so  make  sure  to  read  over  these  options.  By  default,  Laravel  is  configured  to  use  the  file 
cache  driver,  which  stores  the  serialized,  cached  objects  in  the  filesystem.  Lor  larger  applications, 
it  is  recommended  that  you  use  an  in-memory  cache  such  as  Memcached  or  APC.  You  may  even 
configure  multiple  cache  configurations  for  the  same  driver. 

Cache  Prerequisites 

Database 

When  using  the  database  cache  driver,  you  will  need  to  setup  a table  to  contain  the  cache  items. 
You’ll  find  an  example  Schema  declaration  for  the  table  below: 


1 Schema :: create( ' cache ' , function($table)  { 
$table- > string ( 1 key  1 ) - >unique( ) ; 
$table- >text( ’value 1 ) ; 

Stable- > integer( 1 expiration ’ ) ; 

5 }); 


141http://memcached.org 

142http://redis.io 
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Memcached 

Using  the  Memcached  cache  requires  the  Memcached  PECL  package143  to  be  installed. 
The  default  configuration  uses  TCP/IP  based  on  MemcachedcaddServer144: 

1 'memcached'  =>  [ 

2 [ 

3 'host'  =>  '127.0.0.1', 

4 'port'  =>  11211, 

5 'weight'  =>  100 

6 ], 

7 ], 


You  may  also  set  the  host  option  to  a UNIX  socket  path.  If  you  do  this,  the  port  option  should  be 
set  to  0: 

1 'memcached'  =>  [ 

2 [ 

'host'  =>  ' /var/run/memcached/memcached . sock ' , 

4 'port'  =>  0, 

5 'weight'  =>  100 

6 ], 

7 ], 


Redis 

Before  using  a Redis  cache  with  Laravel,  you  will  need  to  install  the  predis/predis  package  (~1.0) 
via  Composer. 

For  more  information  on  configuring  Redis,  consult  its  Laravel  documentation  page. 

Cache  Usage 

Obtaining  A Cache  Instance 

The  1 1 luminate\Contracts\Cache\Factory  and  1 1 luminate\Contracts\Cache\Repository  con- 
tracts provide  access  to  Laravel’s  cache  services.  The  Factory  contract  provides  access  to  all  cache 

143http://pecl.php.net/package/memcached 

144http://php.net/manual/en/memcached.addserver.php 
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drivers  defined  for  your  application.  The  Repository  contract  is  typically  an  implementation  of  the 
default  cache  driver  for  your  application  as  specified  by  your  cache  configuration  file. 

However,  you  may  also  use  the  Cache  facade,  which  is  what  we  will  use  throughout  this  documen- 
tation. The  Cache  facade  provides  convenient,  terse  access  to  the  underlying  implementations  of  the 
Laravel  cache  contracts. 

For  example,  let’s  import  the  Cache  facade  into  a controller: 

1 < ?php 

2 

3 namespace  App\Http\Control lers; 

4 

5 use  Cache; 

6 

7 class  UserController  extends  Controller 

8 { 

9 /** 

10  * Show  a list  of  all  users  of  the  application. 

11  * 

12  * §return  Response 

13  */ 

14  public  function  index() 

15  { 

16  lvalue  = Cache :: get( ' key ') ; 

17 

18  // 

19  } 

20  } 


Accessing  Multiple  Cache  Stores 

Using  the  Cache  facade,  you  may  access  various  cache  stores  via  the  store  method.  The  key  passed 
to  the  store  method  should  correspond  to  one  of  the  stores  listed  in  the  stores  configuration  array 
in  your  cache  configuration  file: 


1 lvalue  = Cache :: store( ' fi le ')- >get( ' foo ') ; 

2 

3 Cache: :store( 'redis' )->put( 'bar' , 'baz',  10); 
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Retrieving  Items  From  The  Cache 

The  get  method  on  the  Cache  facade  is  used  to  retrieve  items  from  the  cache.  If  the  item  does  not 
exist  in  the  cache,  null  will  be  returned.  If  you  wish,  you  may  pass  a second  argument  to  the  get 
method  specifying  the  custom  default  value  you  wish  to  be  returned  if  the  item  doesn’t  exist: 


1 lvalue  = Cache :: get( ' key ') ; 

2 

3 lvalue  = Cache :: get( ’ key  1 , 'default'); 


You  may  even  pass  a Closure  as  the  default  value.  The  result  of  the  Closure  will  be  returned  if 
the  specified  item  does  not  exist  in  the  cache.  Passing  a Closure  allows  you  to  defer  the  retrieval  of 
default  values  from  a database  or  other  external  service: 


1 

lvalue  = Cache 

:get(’key',  function()  { 

2 

return  DB : 

table( . . . ) - >get( ) ; 

3 

}); 

Checking  For  Item  Existence 

The  has  method  may  be  used  to  determine  if  an  item  exists  in  the  cache: 


1 if  (Cache :: has( 1 key  1 ) ) { 

2 // 

3 } 


Incrementing  / Decrementing  Values 

The  increment  and  decrement  methods  may  be  used  to  adjust  the  value  of  integer  items  in  the 
cache.  Both  of  these  methods  optionally  accept  a second  argument  indicating  the  amount  by  which 
to  increment  or  decrement  the  item’s  value: 
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1 Cache :: increment^  ' key ') ; 

2 

3 Cache :: increment^  ' key ' , $amount); 

4 

5 Cache :: decrement^  ' key ') ; 

6 

7 Cache :: decrement^  ' key ' , $amount); 


Retrieve  Or  Update 

Sometimes  you  may  wish  to  retrieve  an  item  from  the  cache,  but  also  store  a default  value  if  the 
requested  item  doesn’t  exist.  For  example,  you  may  wish  to  retrieve  all  users  from  the  cache  or,  if 
they  don’t  exist,  retrieve  them  from  the  database  and  add  them  to  the  cache.  You  may  do  this  using 
the  Cache:  : remember  method: 


1 

lvalue  = Cache 

: remember (' users  1 , Iminutes,  function()  { 

2 

return  DB : 

table( ' users ' ) - >get( ) ; 

3 

}); 

If  the  item  does  not  exist  in  the  cache,  the  Closure  passed  to  the  remember  method  will  be  executed 
and  its  result  will  be  placed  in  the  cache. 

You  may  also  combine  the  remember  and  forever  methods: 


1 

lvalue  = Cache 

: rememberForever( ' users ' , function()  { 

2 

return  DB : 

table( ' users ' ) - >get( ) ; 

3 

}); 

Retrieve  And  Delete 

If  you  need  to  retrieve  an  item  from  the  cache  and  then  delete  it,  you  may  use  the  pull  method.  Like 
the  get  method,  null  will  be  returned  if  the  item  does  not  exist  in  the  cache: 

1 lvalue  = Cache : : pul  1 ( ' key ' ) ; 
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Storing  Items  In  The  Cache 

You  may  use  the  put  method  on  the  Cache  facade  to  store  items  in  the  cache.  When  you  place  an 
item  in  the  cache,  you  will  need  to  specify  the  number  of  minutes  for  which  the  value  should  be 
cached: 

1 Cache :: put( ' key ' , 'value',  $minutes); 


Instead  of  passing  the  number  of  minutes  until  the  item  expires,  you  may  also  pass  a PHP  DateTime 
instance  representing  the  expiration  time  of  the  cached  item: 


1 SexpiresAt  = Carbon :: now( )->addMinutes(10); 

2 

3 Cache :: put( ' key ' , 'value',  SexpiresAt); 


The  add  method  will  only  add  the  item  to  the  cache  if  it  does  not  already  exist  in  the  cache  store. 
The  method  will  return  true  if  the  item  is  actually  added  to  the  cache.  Otherwise,  the  method  will 
return  false: 


1 Cache :: add( ' key ' , 'value',  $minutes); 


The  forever  method  may  be  used  to  store  an  item  in  the  cache  permanently.  These  values  must  be 
manually  removed  from  the  cache  using  the  forget  method: 


1 Cache :: forever (' key ' , 'value'); 


Removing  Items  From  The  Cache 

You  may  remove  items  from  the  cache  using  the  forget  method  on  the  Cache  facade: 
1 Cache :: forget( ' key ') ; 
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You  may  clear  the  entire  cache  using  the  flush  method: 


1 Cache : : f lush( ) ; 


Flushing  the  cache  does  not  respect  the  cache  prefix  and  will  remove  all  entries  from  the  cache. 
Consider  this  carefully  when  clearing  a cache  which  is  shared  by  other  applications. 

Cache  Tags 


Note:  Cache  tags  are  not  supported  when  using  the  file  or  database  cache  drivers. 
Furthermore,  when  using  multiple  tags  with  caches  that  are  stored  “forever”,  performance 
will  be  best  with  a driver  such  as  memcached,  which  automatically  purges  stale  records. 


Storing  Tagged  Cache  Items 

Cache  tags  allow  you  to  tag  related  items  in  the  cache  and  then  flush  all  cached  values  that  have 
been  assigned  a given  tag.  You  may  access  a tagged  cache  by  passing  in  an  ordered  array  of  tag 
names.  For  example,  let’s  access  a tagged  cache  and  put  value  in  the  cache: 


1 Cache :: tags( [ ' people ' , ' artists ' ] )- >put( 1 John ' , $john,  $minutes); 

2 

3 Cache :: tags( [ ' people  1 , 1 authors ’ ] )- >put( 1 Anne 1 , $anne,  $minutes); 


However,  you  are  not  limited  to  the  put  method.  You  may  use  any  cache  storage  method  while 
working  with  tags. 

Accessing  Tagged  Cache  Items 


To  retrieve  a tagged  cache  item,  pass  the  same  ordered  list  of  tags  to  the  tags  method: 


1 

$john  = Cache :: tags( [ ' people 1 , 

1 artists ' ] ) - >get( ' John ' ) ; 

2 

3 

$anne  = Cache :: tags( [ ' people ' , 

1 authors ' ] )- >get( 'Anne' ) ; 
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You  may  flush  all  items  that  are  assigned  a tag  or  list  of  tags.  For  example,  this  statement  would 
remove  all  caches  tagged  with  either  people,  authors,  or  both.  So,  both  Anne  and  John  would  be 
removed  from  the  cache: 


1 Cache :: tags( [' people  1 11 , ' authors ' ] )- > flush( ) ; 


In  contrast,  this  statement  would  remove  only  caches  tagged  with  authors,  so  Anne  would  be 
removed,  but  not  John. 


1 Cache : : tags( ' authors  1 ) - > f lush( ) ; 


Adding  Custom  Cache  Drivers 

To  extend  the  Laravel  cache  with  a custom  driver,  we  will  use  the  extend  method  on  the  Cache 
facade,  which  is  used  to  bind  a custom  driver  resolver  to  the  manager.  Typically,  this  is  done  within 
a service  provider. 

For  example,  to  register  a new  cache  driver  named  “mongo”: 

1 < ?php 

2 

3 namespace  App\Providers; 

4 

5 use  Cache; 

6 use  App\Extensions\MongoStore; 

7 use  Illuminate\Support\ServiceProvider; 

8 

9 class  CacheServiceProvider  extends  ServiceProvider 

10  { 

11  /** 

12  * Perform  post-registration  booting  of  services. 

13  * 

14  * § return  void 

15  */ 

16  public  function  boot() 

17  { 

18 
19 


Cache :: extend( ' mongo ' , function($app)  { 

return  Cache: :repository(new  MongoStore); 


Cache 


260 


20  }); 

21  } 

22 

23  /** 

24  * Register  bindings  in  the  container . 

25  * 

26  * §return  void 

27  */ 

public  function  registerQ 

29  { 

30  // 

31  } 

32  } 


The  first  argument  passed  to  the  extend  method  is  the  name  of  the  driver.  This  will  correspond  to 
your  driver  option  in  the  conf  ig/cache . php  configuration  file.  The  second  argument  is  a Closure 
that  should  return  an  Illuminate\Cache\Repository  instance.  The  Closure  will  be  passed  an  $app 
instance,  which  is  an  instance  of  the  service  container. 

The  call  to  Cache : : extend  could  be  done  in  the  boot  method  of  the  default  App\Providers\AppServiceProvider 
that  ships  with  fresh  Laravel  applications,  or  you  may  create  your  own  service  provider  to  house 
the  extension  - just  don’t  forget  to  register  the  provider  in  the  conf  ig/app . php  provider  array. 

To  create  our  custom  cache  driver,  we  first  need  to  implement  the  1 1 1 um  i nate\Contracts  \Cache\Store 
contract  contract.  So,  our  MongoDB  cache  implementation  would  look  something  like  this: 

1 < ?php 

2 

3 namespace  App\Extensions; 

4 

5 class  MongoStore  implements  \Illuminate\Contracts\Cache\Store 

6 { 


7 

public 

function 

get($key)  {} 

8 

public 

function 

put($key,  $value,  $min 

utes) 

{} 

9 

public 

function 

increment($key , 

$value 

= 1) 

{} 

10 

public 

function 

decrement($key , 

Svalue 

= 1) 

{} 

11 

public 

function 

forever ($key,  $value) 

{} 

12 

public 

function 

forget ($key)  {} 

13 

public 

function 

flush()  {} 

14 

public 

function 

getPrefixQ  {} 

15  } 
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We  just  need  to  implement  each  of  these  methods  using  a MongoDB  connection.  Once  our 
implementation  is  complete,  we  can  finish  our  custom  driver  registration: 


1 Cache :: extend( ' mongo 1 , function(Sapp)  { 

return  Cache  repository(new  MongoStore); 

3 }); 


Once  your  extension  is  complete,  simply  update  your  conf  ig/cache . php  configuration  file’s  driver 
option  to  the  name  of  your  extension. 

If  you’re  wondering  where  to  put  your  custom  cache  driver  code,  consider  making  it  available  on 
Packagist!  Or,  you  could  create  an  Extensions  namespace  within  your  app  directory.  However,  keep 
in  mind  that  Laravel  does  not  have  a rigid  application  structure  and  you  are  free  to  organize  your 
application  according  to  your  preferences. 

Events 

To  execute  code  on  every  cache  operation,  you  may  listen  for  the  events  fired  by  the  cache.  Typically, 
you  should  place  these  event  listeners  within  your  EventServiceProvider: 

/** 

* The  event  listener  mappings  for  the  application. 

* 

* §var  array 

V 

protected  Slisten  7 [ 

' II luminate\Cache\Events\CacheHit ' =>  [ 

1 App\Listeners\LogCacheHit ' , 

], 

' II luminate\Cache\Events\CacheMissed 1 =>  [ 

1 App\Listeners\LogCacheMissed ' , 

1, 

' 1 1 luminate\Cache\Events\KeyForgotten 1 =>  [ 

1 App\Listeners\LogKeyForgotten ' , 

], 

' 1 1 luminate\Cache\Events\KeyWr itten ' =>  [ 

1 App\Listeners\LogKeyWritten ' , 

], 


1 

2 

3 

4 

5 

6 

7 

8 
9 

10 

11 

12 

13 

14 

15 

16 

17 

18 

19 

20 
21 
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22  ]; 


Collections 


• Introduction 

• Creating  Collections 

• Available  Methods 

Introduction 

The  Illuminate \Support  \Co  1 1 ect  i on  class  provides  a fluent,  convenient  wrapper  for  working  with 
arrays  of  data.  For  example,  check  out  the  following  code.  We’ll  use  the  collect  helper  to  create 
a new  collection  instance  from  the  array,  run  the  strtoupper  function  on  each  element,  and  then 
remove  all  empty  elements: 

1 $collection  = col lect( [ ' taylor 1 , 'abigail',  null] )->map(function  ($name)  { 
return  strtoupper($name) ; 

3 }) 

4 - >reject( function  ($name)  { 

5 return  empty($name) ; 

6 }); 


As  you  can  see,  the  Collection  class  allows  you  to  chain  its  methods  to  perform  fluent  mapping 
and  reducing  of  the  underlying  array.  In  general,  every  Col  lection  method  returns  an  entirely  new 
Collection  instance. 


Creating  Collections 

As  mentioned  above,  the  collect  helper  returns  a new  1 1 luminate\Support\Col lection  instance 
for  the  given  array.  So,  creating  a collection  is  as  simple  as: 


1 $collection  = collect([l,  2,  3]); 


By  default,  collections  of  Eloquent  models  are  always  returned  as  Collection  instances;  however, 
feel  free  to  use  the  Collection  class  wherever  it  is  convenient  for  your  application. 
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Available  Methods 

For  the  remainder  of  this  documentation,  we’ll  discuss  each  method  available  on  the  Collection 
class.  Remember,  all  of  these  methods  may  be  chained  for  fluently  manipulating  the  underlying 
array.  Furthermore,  almost  every  method  returns  a new  Collection  instance,  allowing  you  to 
preserve  the  original  copy  of  the  collection  when  necessary. 

You  may  select  any  method  from  this  table  to  see  an  example  of  its  usage: 

<style>  A>  #collection-method-list  > p { A>  column-count:  3;  -moz-column-count:  3;  -webkit- 
column-count:  3;  A>  column-gap:  2em;  -moz-column-gap:  2em;  -webkit-column-gap:  2em;  A>  } A> 
A>  #collection-method-list  a { A>  display:  block;  A>  } 

</style> 

<div  id=”collection-method-list”  markdown=”l”>  all  avg  chunk  collapse  contains  count  diff  each 
every  except  filter  first  flatten  flip  forget  forPage  get  groupBy  has  implode  intersect  isEmpty  keyBy 
keys  last  map  max  merge  min  only  pluck  pop  prepend  pull  push  put  random  reduce  reject  reverse 
search  shift  shuffle  slice  sort  sortBy  sortByDesc  splice  sum  take  toArray  tojson  transform  unique 
values  where  whereLoose  wherein  wherelnLoose  zip  </div> 

Method  Listing 

<style>  A>  #collection-method  code  { A>  font-size:  14px;  A>  } A>  A>  #collection-method:not(.first- 
collection-method)  { A>  margin-top:  50px;  A>  } 

</style> 

a i i ( ) {#collection-method  .first-collection-method} 

The  all  method  simply  returns  the  underlying  array  represented  by  the  collection: 


1 collect([l,  2,  3])->all(); 

2 

3 //  [1,  2,  3] 


avg()  {#collection-method} 

The  avg  method  returns  the  average  of  all  items  in  the  collection: 
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1 collect([l,  2,  3,  4,  5])->avg(); 

2 

3 //  3 


If  the  collection  contains  nested  arrays  or  objects,  you  should  pass  a key  to  use  for  determining 
which  values  to  calculate  the  average: 


1 $col lection  = collect([ 

['name'  =>  'JavaScript:  The  Good  Parts',  'pages'  =>  176], 

['name'  =>  'JavaScript:  The  Definitive  Guide',  'pages'  =>  1096], 

4 ]); 

5 

6 $col lection- >avg( ' pages ') ; 

7 

8 //  636 


chunk( ) {#collection-method} 

The  chunk  method  breaks  the  collection  into  multiple,  smaller  collections  of  a given  size: 


1 Scollection  = collect([l,  2,  3,  4,  5,  6,  7]); 

2 

3 $chunks  = $col lection- >chunk(4) ; 

4 

5 $chunks->toArray( ) ; 

6 

7 //  [[1,  2,  3,  4],  [5,  6,  7]] 


This  method  is  especially  useful  in  views  when  working  with  a grid  system  such  as  Bootstrap145. 
Imagine  you  have  a collection  of  Eloquent  models  you  want  to  display  in  a grid: 


145 


’http://getbootstrap.eom/css/#grid 
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1 @foreach  ($products->chunk(3)  as  $chunk) 

2 <div  class="row"> 

§foreach  ($chunk  as  Sproduct) 

<div  class="col -xs-4" > { { $product->name  }}</div> 

5 ©endforeach 

6 </div> 

7 @endforeach 


col lapse( ) {#collection-method} 

The  collapse  method  collapses  a collection  of  arrays  into  a flat  collection: 


1 $collection  = col lect( [ [1 , 2,  3],  [4,  5,  6],  [7,  8,  9]]); 

2 

3 $collapsed  = $collection- >col lapse( ) ; 

4 

5 $collapsed->all( ); 

6 

7 //  [1,  2,  3,  4,  5,  6,  7,  8,  9] 


contains( ) {#collection-method} 

The  contains  method  determines  whether  the  collection  contains  a given  item: 

1 $col lection  = col lect( [' name ' =>  'Desk',  'price'  =>  100]); 

2 

3 $col lection- >contains( ' Desk ') ; 

4 

5 //  true 

6 

7 $col lection- >contains( ' New  York'); 

8 

9 //  false 


You  may  also  pass  a key  / value  pair  to  the  contains  method,  which  will  determine  if  the  given  pair 
exists  in  the  collection: 
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1 

$col lection  = collect([ 

2 

['product'  =>  'Desk1,  'price' 

=>  200] , 

3 

['product'  =>  'Chair',  ’price 

=>  100], 

4 

]); 

5 

6 

$col lection- > contains ( 1 product 1 , 

Bookcase ' ) ; 

7 

8 

//  false 

Finally,  you  may  also  pass  a callback  to  the  contains  method  to  perform  your  own  truth  test: 


1 Icollection  = collect([l,  2,  3,  4,  5]); 

2 

3 $col lection- >contains( function  ($key,  $value)  { 

4 return  lvalue  > 5; 

5 }); 

6 

7 //  false 


count()  {#collection-method} 

The  count  method  returns  the  total  number  of  items  in  the  collection: 


1 Icollection  = collect([l,  2,  3,  4]); 

2 

3 $col lection- >count( ) ; 

4 

5 //  4 


diff()  {#collection-method} 

The  di  f f method  compares  the  collection  against  another  collection  or  a plain  PHP  array: 


Collections 


268 


1 $collection  = collect([l,  2,  3,  4,  5]); 

2 

3 $diff  = $collection->diff( [2,  4,  6,  8]); 

4 

5 $di f f - >al 1 ( ) ; 

6 

7 //  [1,  3,  5] 


each( ) {#collection-method} 

The  each  method  iterates  over  the  items  in  the  collection  and  passes  each  item  to  a given  callback: 

1 $collection  = $col lection- >each( function  ($item,  $key)  { 

2 // 

3 }); 


Return  false  from  your  callback  to  break  out  of  the  loop: 


1 $collection  = $col lection- >each( function  ($item,  $key)  { 
if  (/*  some  condition  */)  { 
return  false; 

4 } 

5 }); 


every ( ) {#collection-method} 

The  every  method  creates  a new  collection  consisting  of  every  n-th  element: 

1 $collection  = col lect( [ ' a ' , ’b1,  'c',  ' d ' , 'e',  ' f ' ] ) ; 

2 

3 $col lection- >every(4) ; 

4 

5 //  [ 'a' , ' e ' ] 
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You  may  optionally  pass  offset  as  the  second  argument: 


1 $col lection- >every(4,  1); 

2 

3 //  ['b',  ’ f 1 ] 


except( ) {#collection-method} 

The  except  method  returns  all  items  in  the  collection  except  for  those  with  the  specified  keys: 


1 Icollection  = col lect( [ ' product_id ' =>  1,  'name'  =>  'Desk',  'price1  =>  100,  'dis\ 

2 count'  =>  false]); 

3 

4 $filtered  = $col lection- >except( [' price ' , 'discount']); 

5 

6 $f i ltered- >al 1 ( ) ; 

7 

8 //  [ ' product_id ' =>  1,  'name'  =>  'Desk'] 


For  the  inverse  of  except,  see  the  only  method. 

fiiter()  {#collection-method} 

The  filter  method  filters  the  collection  by  a given  callback,  keeping  only  those  items  that  pass  a 
given  truth  test: 

1 $collection  = collect([l,  2,  3,  4]); 

2 

3 $filtered  = $col lection- > fi lter( function  (lvalue,  $key)  { 

4 return  lvalue  > 2; 

5 }); 

6 

7 |f i ltered- >al 1 () ; 

8 

9 //  [3,  4] 


For  the  inverse  of  filter,  see  the  reject  method. 
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firsto  {#collection-method} 

The  f i rst  method  returns  the  first  element  in  the  collection  that  passes  a given  truth  test: 


1 collect([l,  2,  3,  4] )-> first( function  ($key,  lvalue)  { 
return  lvalue  > 2; 

3 }); 

4 

5 //  3 


You  may  also  call  the  first  method  with  no  arguments  to  get  the  first  element  in  the  collection.  If 
the  collection  is  empty,  null  is  returned: 


1 collect([l,  2,  3,  4] )-> f irst( ) ; 

2 

3 //  1 


fiattenQ  {#collection-method} 

The  flatten  method  flattens  a multi-dimensional  collection  into  a single  dimension: 


1 Icol lection  = col lect( [' name ' =>  'taylor',  'languages'  =>  ['php',  ' javascript ']] \ 

2 ); 

3 

4 Iflattened  = Icol lection- > flatten( ) ; 

5 

6 If lattened- >al 1 ( ) ; 

7 

8 //  ['taylor',  'php',  'javascript']; 


fiipO  {#collection-method} 

The  flip  method  swaps  the  collection’s  keys  with  their  corresponding  values: 
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1 

$col lection  = collect( 

'name'  => 

'taylor',  'framework'  =>  'laravel']); 

2 

3 

$f lipped  = $col lection- 

> f i ip( ) ; 

4 

5 

$ f 1 ipped->al  1 ( ) ; 

6 

7 

//  ['taylor'  =>  'name' 

' laravel ' 

=>  ’framework’] 

forgeto  {#collection-method} 

The  forget  method  removes  an  item  from  the  collection  by  its  key: 

1 $col lection  = col lect( [' name ' =>  'taylor',  'framework'  =>  'laravel']); 

2 

3 $col lection- > forget( ' name ') ; 

4 

5 $col lection- >al 1 () ; 

6 

7 //  [framework'  =>  'laravel'] 


Note:  Unlike  most  other  collection  methods,  forget  does  not  return  a new  modified 
collection;  it  modifies  the  collection  it  is  called  on. 


forPage( ) {#collection-method} 

The  forPage  method  returns  a new  collection  containing  the  items  that  would  be  present  on  a given 
page  number: 

1 $collection  = collect([l,  2,  3,  4,  5,  6,  7,  8,  9]); 

2 

3 $chunk  = $collection->forPage(2,  3); 

4 

5 $chunk- >al 1 ( ) ; 

6 
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7 //  [4,  5,  6] 

The  method  requires  the  page  number  and  the  number  of  items  to  show  per  page,  respectively. 

get()  {#collection-method} 

The  get  method  returns  the  item  at  a given  key.  If  the  key  does  not  exist,  null  is  returned: 

1 $col lection  = col lect( [' name ' =>  'taylor',  'framework'  =>  'laravel']); 

2 

3 lvalue  = $col lection- >get( ' name ') ; 

4 

5 //  taylor 


You  may  optionally  pass  a default  value  as  the  second  argument: 

1 $col lection  = col lect( [' name ' =>  'taylor',  'framework'  =>  'laravel']); 

2 

3 lvalue  = Icol lection- >get( ’ foo 1 , ' default-value ' ) ; 

4 

5 //  default-value 


You  may  even  pass  a callback  as  the  default  value.  The  result  of  the  callback  will  be  returned  if  the 
specified  key  does  not  exist: 

1 |col lection- >get( ' emai 1 ' , function  ()  { 
return  'default-value1; 

3 }); 

4 

5 //  default-value 


groupBy ( ) {#collection-method} 

The  groupBy  method  groups  the  collection’s  items  by  a given  key: 
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1 

$col lection  = 

col lect( 

t 

2 

[ ' account. 

_id ' =>  ' 

account-xl0 ' , 

'product'  => 

1 Chair ' ] , 

3 

[ ' account. 

_id ' =>  ' 

account-xl0 ' , 

'product'  => 

1 Bookcase ' 

4 

[ ' account. 

_id ' =>  ' 

account-xll ' , 

'product'  => 

' Desk ' ] , 

5 ]); 

6 

7 $grouped  = $col lection- >groupBy( ' account_id ') ; 

8 

9 $grouped->toArray( ) ; 

10 

11  /* 


13 

1 account-xl0 ' 

= > 

t 

14 

[ ' account. 

_id ' 

=>  ' account-xl0 ' , 

'product'  => 

' Chair ' ] , 

15 

[ ' account. 

_id ' 

=>  ' account-xl0 ' , 

'product'  => 

' Bookcase ' ] , 

16 

L 

17 

' account-xll ' 

=> 

[ 

18 

[ ' account. 

_id ' 

=>  ' account-xll ' , 

'product'  => 

' Desk  ' ] , 

20  ] 
21  */ 


In  addition  to  passing  a string  key,  you  may  also  pass  a callback.  The  callback  should  return  the 
value  you  wish  to  key  the  group  by: 

1 $grouped  = $col lection- >groupBy( function  ($item,  $key)  { 
return  substr($item [ ' account_id ' ] , -3); 

3 }); 

4 

5 $grouped->toArray( ) ; 

6 

7 /* 

8 [ 

'xl0'  =>  [ 


10 

[ ' account_id ' 

=>  1 account-xl0 1 , 

'product'  => 

' Chair ' ] , 

11 

[ 1 account_id ' 

=>  1 account-xl0 1 , 

'product'  => 

' Bookcase ' ] , 

12 

], 

13 

' xll 1 =>  [ 

14 

[ 1 account_id ' 

=>  1 account-xll 1 , 

'product'  => 

' Desk  ' ] , 

15 

L 

16 

] 
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17  */ 


has( ) {#collection-method} 

The  has  method  determines  if  a given  key  exists  in  the  collection: 

1 $col lection  = col lect( [ ' account_id ' =>  1,  'product'  =>  'Desk']); 

2 

3 $col lection- >has( ' emai 1 ') ; 

4 

5 //  false 


implode( ) {#collection-method} 

The  implode  method  joins  the  items  in  a collection.  Its  arguments  depend  on  the  type  of  items  in 
the  collection. 

If  the  collection  contains  arrays  or  objects,  you  should  pass  the  key  of  the  attributes  you  wish  to 
join,  and  the  “glue”  string  you  wish  to  place  between  the  values: 


1 $col lection  = collect([ 

[ ’ account_id ’ =>  1,  'product1 2  =>  'Desk'], 

[ ' account_id ' =>  2,  'product'  =>  'Chair'], 

4 ]); 

5 

6 $col lection- > implode( ' product ' , ',  '); 

7 

8 //  Desk,  Chair 


If  the  collection  contains  simple  strings  or  numeric  values,  simply  pass  the  “glue”  as  the  only 
argument  to  the  method: 


1 collect([l,  2,  3,  4,  5] )-> implode( ' - ' ) ; 

2 
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3 //  '1-2-3-4-5' 


intersect( ) {#collection-method} 

The  intersect  method  removes  any  values  that  are  not  present  in  the  given  array  or  collection: 

1 $collection  = col lect( [' Desk  1 , 'Sofa',  'Chair']); 

2 

3 Sintersect  = $col lection- > intersect( [’ Desk ' , 'Chair',  'Bookcase']); 

4 

5 Sintersect- >al 1 () ; 

6 

7 //  [0  =>  'Desk' , 2 =>  'Chair' ] 


As  you  can  see,  the  resulting  collection  will  preserve  the  original  collection’s  keys. 

isEmpty ( ) {#collection-method} 

The  isEmpty  method  returns  true  if  the  collection  is  empty;  otherwise,  false  is  returned: 

1 col lect( [ ] ) - > isEmpty ( ) ; 

2 

3 //  true 


keyBy ( ) {#collection-method} 

Keys  the  collection  by  the  given  key: 
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1 $col lection  = collect([ 

[ ' product_id ' =>  'prod-100',  'name'  =>  'desk'], 

[ ' product_id ' =>  'prod-200',  'name'  =>  'chair'], 

4 ]); 

5 

6 $keyed  = $col lection- >keyBy( ' product_id ') ; 

7 

8 $keyed- >al 1 ( ) ; 

9 

10  /* 

11  [ 

'prod-100'  =>  [ ' product_id ' =>  'prod-100',  'name'  =>  'Desk'], 
'prod-200'  =>  [ ' product_id ' =>  'prod-200',  'name'  =>  'Chair'], 

14  ] 

15  */ 


If  multiple  items  have  the  same  key,  only  the  last  one  will  appear  in  the  new  collection. 

You  may  also  pass  your  own  callback,  which  should  return  the  value  to  key  the  collection  by: 

1 $keyed  = $col lection- >keyBy( function  ($item)  { 
return  strtoupper($item [ ' product_id 1 ] ) ; 

3 }); 

4 

5 $keyed- >al 1 ( ) ; 

6 

7 /* 

8 [ 

'PROD-100'  =>  [ ' product_id ' =>  'prod-100',  'name'  =>  'Desk'], 

10  'PROD-200'  =>  [ ' product_id ' =>  'prod-200',  'name'  =>  'Chair'], 

11  ] 

12  */ 


keys()  {#collection-method} 

The  keys  method  returns  all  of  the  collection’s  keys: 
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1 $col lection  = collect([ 

'prod-100'  =>  [ 1 product_id 1 =>  ’prod-100',  'name'  =>  'Desk'], 
'prod-200'  =>  [ 1 product_id 1 =>  'prod-200',  'name'  =>  'Chair'], 

4 ]); 

5 

6 $keys  = $collection->keys( ) ; 

7 

8 $keys->all( ) ; 

9 

10  //  ['prod-100',  ’prod-2001] 


iast()  {#collection-method} 

The  last  method  returns  the  last  element  in  the  collection  that  passes  a given  truth  test: 


1 collect([l,  2,  3,  4] )-> last( function  ($key,  lvalue)  { 
return  lvalue  < 3; 

3 }); 

4 

5 //  2 


You  may  also  call  the  last  method  with  no  arguments  to  get  the  last  element  in  the  collection.  If 
the  collection  is  empty,  null  is  returned: 


1 collect([l,  2,  3,  4])->last(); 

2 

3 //  4 


map()  {#collection-method} 

The  map  method  iterates  through  the  collection  and  passes  each  value  to  the  given  callback.  The 
callback  is  free  to  modify  the  item  and  return  it,  thus  forming  a new  collection  of  modified  items: 
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1 Icollection  = collect([l,  2,  3,  4,  5]); 

2 

3 Imultiplied  = $col lection- >map( function  ($item,  $key)  { 

4 return  litem  * 2; 

5 }); 

6 

7 Imultipl ied- >al  1 ( ) ; 

8 

9 //  [2,  4,  6,  8,  10] 


Note:  Like  most  other  collection  methods,  map  returns  a new  collection  instance;  it  does 
not  modify  the  collection  it  is  called  on.  If  you  want  to  transform  the  original  collection, 
use  the  transform  method. 


max( ) {#collection-method} 

The  max  method  return  the  maximum  value  of  a given  key: 

1 $max  = col lect( [ [ ' foo ' =>  10],  ['foo'  =>  20] ] ) - >max( ' foo ' ) ; 

2 

3 //  20 

4 

5 $max  = collect([l,  2,  3,  4,  5])->max(); 

6 

7 //  5 


mergeO  {#collection-method} 

The  merge  method  merges  the  given  array  into  the  collection.  Any  string  key  in  the  array  matching 
a string  key  in  the  collection  will  overwrite  the  value  in  the  collection: 
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1 $col lection  = col lect( [ ' product_id ' =>  1,  'name'  =>  'Desk']); 

2 

3 $merged  = $col lection- >merge( [' price ' =>  100,  'discount'  =>  false]); 

4 

5 $merged->all( ) ; 

6 

7 //  [ ' product_id ' =>  1,  'name'  =>  'Desk',  'price'  =>  100,  'discount'  =>  false] 


If  the  given  array’s  keys  are  numeric,  the  values  will  be  appended  to  the  end  of  the  collection: 

1 $collection  = col lect( [' Desk ' , 'Chair']); 

2 

3 $merged  = $col lection- >merge( [' Bookcase ' , 'Door']); 

4 

5 $merged- >al 1 ( ) ; 

6 

7 //  ['Desk',  'Chair',  'Bookcase',  'Door'] 


min( ) {#collection-method} 


The  min  method  return  the  minimum  value  of  a given  key: 


only ( ) {#collection-method} 


The  only  method  returns  the  items  in  the  collection  with  the  specified  keys: 
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1 

$col lection  = collect([ 

product_id'  =>  1,  'name'  =>  'Desk', 

'price'  =>  100,  'dis\ 

2 

count ' =>  false] ) ; 

3 

4 

$filtered  = $collection 

>only( [ ' product_id ' , 'name']); 

5 

6 

$f i ltered- >al 1 ( ) ; 

7 

8 

//  [ ' product_id ' =>  1, 

name ' =>  ' Desk ' ] 

For  the  inverse  of  only,  see  the  except  method. 

piuck()  {#collection-method} 

The  pluck  method  retrieves  all  of  the  collection  values  for  a given  key: 

1 $col lection  = collect([ 

[ ' product_id ' =>  ' prod-100',  'name'  =>  'Desk'], 

[ ' product_id ' =>  'prod-2001,  'name'  =>  'Chair'], 

4 ]); 

5 

6 $plucked  = $col lection- >pluck( ' name ') ; 

7 

8 $plucked->al 1 ( ) ; 

9 

10  //  ['Desk',  'Chair'] 


You  may  also  specify  how  you  wish  the  resulting  collection  to  be  keyed: 


1 Splucked  = $collection->pluck( 'name' , ' product_id ' ) ; 

2 

3 $plucked->al  1 ( ) ; 

4 

5 //  ['prod-100'  =>  'Desk',  ’prod-2001  =>  'Chair'] 


pop()  {#collection-method} 

The  pop  method  removes  and  returns  the  last  item  from  the  collection: 
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prepend ( ) {#collection-method} 

The  prepend  method  adds  an  item  to  the  beginning  of  the  collection: 

1 $collection  = collect([l,  2,  3,  4,  5]); 

2 

3 $col lection- >prepend(0) ; 

4 

5 $col lection- >al 1 () ; 

6 

7 //  [0,  1,  2,  3,  4,  5] 


You  can  optionally  pass  a second  argument  to  set  the  key  of  the  prepended  item: 


1 $collection  = col lect( [ ' one ' =>  1,  'two',  =>  2]); 

2 

3 $collection->prepend(0,  'zero'); 

4 

5 $col lection- >al 1 () ; 

6 

7 //  ['zero'  =>  0,  'one'  =>  1,  'two',  =>  2] 


puii()  {#collection-method} 

The  pull  method  removes  and  returns  an  item  from  the  collection  by  its  key: 
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1 

$col lection  = col lect( [ ' product_id ' =>  'prod-100', 

' name ' =>  ' Desk ' ] ) ; 

2 

3 

$col lection- > pul  1 ( ' name 1 ) ; 

4 

5 

//  ' Desk ' 

6 

7 

$col lection- >al 1 ( ) ; 

8 

9 

//  [ ' product_id ' =>  'prod-100'] 

push()  {#collection-method} 

The  push  method  appends  an  item  to  the  end  of  the  collection: 

1 $collection  = collect([l,  2,  3,  4]); 

2 

3 $collection->push(5); 

4 

5 $col lection- >al 1 () ; 

6 

7 //  [1,  2,  3,  4,  5] 


put ( ) {#collection-method} 


The  put  method  sets  the  given  key  and  value  in  the  collection: 


1 

$col lection  = collect([ 

product_id'  =>  1,  'name' 

=>  ' Desk ' ] ) ; 

2 

3 

$collection->put( 'price 

, 100); 

4 

5 

$col lection- >al 1 ( ) ; 

6 

7 

//  [ 1 product_id ' =>  1, 

name'  =>  'Desk',  'price' 

=>  100] 
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random( ) {#collection-method} 

The  random  method  returns  a random  item  from  the  collection: 


1 Scollection  = collect([l,  2,  3,  4,  5]); 

2 

3 $col lection- >random( ) ; 

4 

5 //  4 - (retrieved  randomly) 


You  may  optionally  pass  an  integer  to  random.  If  that  integer  is  more  than  1,  a collection  of  items  is 
returned: 


1 $random  = $col lection- >random(3) ; 

2 

3 $random->all( ) ; 

4 

5 //  [2,  4,  5]  - (retrieved  randomly) 


reduce( ) {#collection-method} 

The  reduce  method  reduces  the  collection  to  a single  value,  passing  the  result  of  each  iteration  into 
the  subsequent  iteration: 


1 Scollection  = collect([l,  2,  3]); 

2 

3 $total  = $col lection- >reduce( function  ($carry,  $item)  { 

4 return  Scarry  + $item; 

5 }); 

6 

7 //  6 


The  value  for  $carry  on  the  first  iteration  is  null;  however,  you  may  specify  its  initial  value  by 
passing  a second  argument  to  reduce: 
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1 $col lection- >reduce( function  ($carry,  $item)  { 

2 return  Scarry  + Sitem; 

3 },  4); 

4 

5 //  10 


rejecto  {#collection-method} 

The  reject  method  filters  the  collection  using  the  given  callback.  The  callback  should  return  true 
for  any  items  it  wishes  to  remove  from  the  resulting  collection: 

1 Scollection  = collect([l,  2,  3,  4]); 

2 

3 Sfiltered  = $col lection- >reject( function  (lvalue,  $key)  { 

4 return  lvalue  > 2; 

5 }); 

6 

7 |f i ltered- >al 1 ( ) ; 

8 

9 //  [1,  2] 


For  the  inverse  of  the  reject  method,  see  the  filter  method. 

reverse ( ) {#collection-method} 

The  reverse  method  reverses  the  order  of  the  collection’s  items: 

1 Scollection  = collect([l,  2,  3,  4,  5]); 

2 

3 Sreversed  = |col lection- >reverse( ) ; 

4 

5 Sreversed- >al 1 () ; 

6 

7 //  [5,  4,  3,  2,  1] 
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search ( ) {#collection-method} 

The  search  method  searches  the  collection  for  the  given  value  and  returns  its  key  if  found.  If  the 
item  is  not  found,  false  is  returned. 


1 $collection  = collect([2,  4,  6,  8]); 

2 

3 $col lection- >search(4) ; 

4 

5 //  1 


The  search  is  done  using  a “loose”  comparison.  To  use  strict  comparison,  pass  true  as  the  second 
argument  to  the  method: 


1 $col lection- >search( ' 4 ' , true); 

2 

3 //  false 


Alternatively,  you  may  pass  in  your  own  callback  to  search  for  the  first  item  that  passes  your  truth 
test: 

1 $col lection- >search( function  ($item,  $key)  { 
return  $item  > 5; 

3 }); 

4 

5 //  2 


shifto  {#collection-method} 

The  shift  method  removes  and  returns  the  first  item  from  the  collection: 
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1 

2 

3 

4 

5 

6 

7 

8 
9 


$collection  = collect([l,  2,  3,  4,  5]); 
$col lection- >shi ft( ) ; 

//  1 

$col lection- >al 1 ( ) ; 

//  [2,  3,  4,  5] 


shuffie()  {#collection-method} 

The  shuffle  method  randomly  shuffles  the  items  in  the  collection: 


1 $collection  = collect([l,  2,  3,  4,  5]); 

2 

3 Sshuffled  = $col lection- >shuffle( ) ; 

4 

5 $shuf f led- >al 1 ( ) ; 

6 

7 //  [3,  2,  5,  1,  4]  //  (generated  randomly) 


siiceQ  {#collection-method} 

The  slice  method  returns  a slice  of  the  collection  starting  at  the  given  index: 


1 $collection  = collect([l,  2,  3,  4,  5,  6,  7,  8,  9,  10]); 

2 

3 $slice  = $col lection- >sl ice(4) ; 

4 

5 $sl ice- >al 1 ( ) ; 

6 

7 //  [5,  6,  7,  8,  9,  10] 


If  you  would  like  to  limit  the  size  of  the  returned  slice,  pass  the  desired  size  as  the  second  argument 
to  the  method: 
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1 $slice  = $col lection- >sl ice(4,  2); 

2 

3 $sl ice- >al 1 ( ) ; 

4 

5 //  [5,  6] 


The  returned  slice  will  have  new,  numerically  indexed  keys.  If  you  wish  to  preserve  the  original 
keys,  pass  true  as  the  third  argument  to  the  method. 

sort()  {#collection-method} 

The  sort  method  sorts  the  collection: 

1 $collection  = collect([5,  3,  1,  2,  4]); 

2 

3 Ssorted  = $col lection- >sort( ) ; 

4 

5 $sorted->values( ) - >al 1 ( ) ; 

6 

7 //  [1,  2,  3,  4,  5] 


The  sorted  collection  keeps  the  original  array  keys.  In  this  example  we  used  the  values  method  to 
reset  the  keys  to  consecutively  numbered  indexes. 

For  sorting  a collection  of  nested  arrays  or  objects,  see  the  sortBy  and  sortByDesc  methods. 

If  your  sorting  needs  are  more  advanced,  you  may  pass  a callback  to  sort  with  your  own  algorithm. 
Refer  to  the  PHP  documentation  on  usort146,  which  is  what  the  collection’s  sort  method  calls  under 
the  hood. 

sortBy ()  {#collection-method} 

The  sortBy  method  sorts  the  collection  by  the  given  key: 


146 


)http://php.net/manual/en/function.usort.php#refsectl-function.usort- parameters 
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1 

$col lection 

= col lect( [ 

2 

[ ' name ' 

=>  ' Desk ' , ' 

price'  => 

200]  , 

3 

[ ' name ' 

=>  'Chair', 

'price'  => 

100]  , 

4 

[ ' name ' 

=>  'Bookcase 

1 , ' price ' 

=>  150] 

5 ]); 

6 

7 Ssorted  = $col lection- >sortBy( ' price ') ; 

8 

9 $sorted->values( ) - >al 1 ( ) ; 

10 

11  /* 


13 

[ 

' name ' 

=> 

' Chair  1 , ' price ' => 

100] , 

14 

[ 

' name ' 

=> 

'Bookcase',  'price' 

=>  150] , 

15 

[ 

' name ' 

=> 

' Desk ' , ' price ' => 

200]  , 

16 

17  */ 


The  sorted  collection  keeps  the  original  array  keys.  In  this  example  we  used  the  values  method  to 
reset  the  keys  to  consecutively  numbered  indexes. 

You  can  also  pass  your  own  callback  to  determine  how  to  sort  the  collection  values: 


1 

2 

$col lection 
[ ' name ' 

= col lect( [ 
=>  ' Desk ' , ' 

colors'  =>  | 

[ ' Black ' , 

' Mahogany ' 

]], 

3 

[ ' name ' 

=>  'Chair', 

'colors'  => 

[ ' Black ' 

]], 

4 

[ ' name ' 

=>  'Bookcase 

' , ' colors ' 

=>  [’Red 

'Beige', 

' Brown 

5 ]); 

6 

7 Ssorted  = $col lection- >sortBy( function  (Sproduct,  $key)  { 
return  count($product [ ' colors ' ] ) ; 

9 }); 

10 

11  Ssorted- >values( )- >al 1 () ; 

12 

13  /* 

14  [ 

15  ['name'  =>  'Chair',  'colors'  =>  ['Black']], 

16  ['name'  =>  'Desk',  'colors'  =>  ['Black',  ’Mahogany']], 

['name'  =>  'Bookcase',  'colors'  =>  ['Red',  'Beige',  'Brown']], 
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19  */ 


sortByDesc( ) {#collection-method} 

This  method  has  the  same  signature  as  the  sortBy  method,  but  will  sort  the  collection  in  the  opposite 
order. 

spl ice( ) {#collection-method} 

The  splice  method  removes  and  returns  a slice  of  items  starting  at  the  specified  index: 


1 $collection  = collect([l,  2,  3,  4,  5]); 

2 

3 $chunk  = $collection->splice(2); 

4 

5 $chunk- >al 1 ( ) ; 

6 

7 //  [3,  4,  5] 

8 

9 $col lection- >al 1 () ; 

10 

11  //  [1,  2] 


You  may  pass  a second  argument  to  limit  the  size  of  the  resulting  chunk: 


1 

$collection  = collect([l,  2,  3, 

4,  5]); 

2 

3 

$chunk  = $collection->splice(2, 

i); 

4 

5 

$chunk- >al 1 ( ) ; 

6 

7 

//  [3] 

8 

9 

$col lection- >al 1 ( ) ; 

10 

11 

//  [1,  2,  4,  5] 
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In  addition,  you  can  pass  a third  argument  containing  the  new  items  to  replace  the  items  removed 
from  the  collection: 


1 

$collection  = collect! [1,  2,  3,  4,  5]); 

2 

3 

$chunk  = $collection->splice(2,  1,  [10,  11]); 

4 

5 

$chunk- >al 1 ( ) ; 

6 

7 

//  [3] 

8 

9 

$col lection- >al 1 ( ) ; 

10 

11 

//  [1,  2,  10,  11,  4,  5] 

sum()  {#collection-method} 

The 

sum  method  returns  the  sum  of  all  items  in  the  collection: 

l 

collect([l,  2,  3,  4,  5])->sum(); 

2 

3 

//  15 

If  the  collection  contains  nested  arrays  or  objects,  you  should  pass  a 
which  values  to  sum: 

key  to  use  for  determining 

l 

$col lection  = collect! [ 

2 

['name'  =>  'JavaScript:  The  Good  Parts',  'pages'  =>  176], 

3 

['name'  =>  'JavaScript:  The  Definitive  Guide',  'pages'  => 

1096] , 

4 

]); 

5 

6 

$col lection- > sum ( ' pages ' ) ; 

7 

8 

//  1272 

In  addition,  you  may  pass  your  own  callback  to  determine  which  values  of  the  collection  to  sum: 
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1 

$col lection 

= col lect( [ 

2 

[ ' name ' 

=>  'Chair' , 

'colors'  => 

[ ' Black ' ] ] , 

3 

[ ' name ' 

=>  ' Desk ' , ' 

colors'  =>  | 

/Black',  'Mahogany' 

]], 

4 

[ ' name ' 

=>  'Bookcase 

' , ' colors ' 

=>  [ 1 2 3 4 5 6 7 Red  1 , ’ Beige ' , 

' Brown 

5 ]); 

6 

7 $col lection- >sum( function  ($product)  { 
return  count($product [ ' colors ' ] ) ; 

9 }); 

10 

11  //  6 


take()  {#collection-method} 

The  take  method  returns  a new  collection  with  the  specified  number  of  items: 


1 $collection  = collect([0,  1,  2,  3,  4,  5]); 

2 

3 $chunk  = $col lection- >take(3) ; 

4 

5 $chunk- >al 1 ( ) ; 

6 

7 //  [0,  1,  2] 


You  may  also  pass  a negative  integer  to  take  the  specified  amount  of  items  from  the  end  of  the 
collection: 


1 Scollection  = collect([0,  1,  2,  3,  4,  5]); 

2 

3 $chunk  = $col lection- >take( -2) ; 

4 

5 $chunk- >al 1 ( ) ; 

6 

7 //  [4,  5] 
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toArray ( ) {#collection-method} 

The  toArray  method  converts  the  collection  into  a plain  PHP  array.  If  the  collection’s  values  are 
Eloquent  models,  the  models  will  also  be  converted  to  arrays: 


$col lection  = col lect( [' name ' =>  'Desk',  'price'  =>  200]); 
$col lection- >toArray( ) ; 

/* 

[ 

['name'  =>  'Desk',  'price'  =>  200], 

1 

*/ 


1 

2 

3 

4 

5 

6 

7 

8 
9 


Note:  toArray  also  converts  all  of  its  nested  objects  to  an  array.  If  you  want  to  get  the 
underlying  array  as  is,  use  the  a 1 1 method  instead. 


toJson( ) {#collection-method} 

The  toJson  method  converts  the  collection  into  JSON: 

1 $col lection  = col lect( [' name ' =>  'Desk',  'price'  =>  200]); 

2 

3 $col lection- >toJson( ) ; 

4 

5 //  '{ "name" : "Desk" , "price" : 200} ' 


transform! ) {#collection-method} 

The  transform  method  iterates  over  the  collection  and  calls  the  given  callback  with  each  item  in  the 
collection.  The  items  in  the  collection  will  be  replaced  by  the  values  returned  by  the  callback: 
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1 Icollection  = collect([l,  2,  3,  4,  5]); 

2 

3 $col lection- >transform( function  ($item,  $key)  { 

4 return  litem  * 2; 

5 }); 


6 

7 $col lection- >al 1 () ; 

8 


9 //  [2,  4,  6,  8,  10] 


o 


Note:  Unlike  most  other  collection  methods,  transform  modifies  the  collection  itself.  If  you 
wish  to  create  a new  collection  instead,  use  the  map  method. 


unique( ) {#collection-method} 

The  unique  method  returns  all  of  the  unique  items  in  the  collection: 

1 Icollection  = collect([l,  1,  2,  2,  3,  4,  2]); 

2 

3 lunique  = $collection->unique( ); 

4 

5 $unique->values( ) - >al 1 ( ) ; 

6 

7 //  [1,  2,  3,  4] 

The  returned  collection  keeps  the  original  array  keys.  In  this  example  we  used  the  va  1 ues  method 
to  reset  the  keys  to  consecutively  numbered  indexes. 

When  dealing  with  nested  arrays  or  objects,  you  may  specify  the  key  used  to  determine  uniqueness: 
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1 

$col lection 

= collect( 

[ 

2 

[ ' name ' 

=>  ' iPhone 

6',  'brand'  =>  'Apple',  'type'  => 

' phone ' ] , 

3 

[ ' name ' 

=>  ' iPhone 

5',  'brand'  =>  'Apple',  'type'  => 

' phone ' ] , 

4 

[ ' name ' 

=>  'Apple  Watch',  'brand'  =>  'Apple', 

'type' 

=>  ' watch ' ] , 

5 

[ ' name ' 

=>  'Galaxy 

S6',  'brand1  =>  'Samsung', 

'type' 

=>  ' phone ' ] , 

6 

[ ' name ' 

=>  'Galaxy 

Gear',  'brand'  =>  'Samsung' 

, 'type'  =>  'watch' 

7 ]); 

8 

9 $unique  = $col lection- >unique( ' brand ') ; 

10 

11  $unique- >values( ) - >al  1 ( ) ; 


[’name1  =>  'iPhone  6',  'brand'  =>  'Apple',  'type'  =>  'phone'], 
['name'  =>  'Galaxy  S6',  'brand'  =>  'Samsung',  'type'  =>  'phone'], 


12 

13 

14 

15 

16 

17 

18 


/* 


*/ 


You  may  also  pass  your  own  callback  to  determine  item  uniqueness: 


1 $unique  = $collection->unique(function  ($item)  { 
return  $item [ ' brand ' ] . $item [ ' type ' ] ; 

3 }); 

4 

5 $unique- >values( ) - >al 1 ( ) ; 

6 

7 /* 


9 

[ 

'name'  => 

' iPhone  6 ' , ' 

brand'  => 

'Apple',  'type'  =>  'phone'], 

10 

[ 

'name'  => 

' Apple  Watch ' 

, 'brand' 

=>  ' Apple ' , 

' type ' =>  ' watch ' ] 

11 

[ 

'name'  => 

' Galaxy  S6 ' , 

'brand'  => 

' Samsung ' , 

' type ' =>  ' phone ' ] 

12 

[ 

'name'  => 

'Galaxy  Gear' 

, 'brand' 

=>  'Samsung' 

, 'type'  =>  'watch 

14  */ 


values( ) {#collection-method} 

The  values  method  returns  a new  collection  with  the  keys  reset  to  consecutive  integers: 
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1 $col lection  = collect([ 

10  =>  ['product'  =>  'Desk',  'price'  =>  200], 

11  =>  ['product'  =>  'Desk',  'price'  =>  200] 

4 ]); 

5 

6 lvalues  = $col lection- >values( ) ; 

7 

8 lvalues- >all( ) ; 

9 

10  /* 

11  [ 

0 =>  ['product'  =>  'Desk',  'price'  =>  200], 

1 =>  ['product'  =>  'Desk',  'price'  =>  200], 

14  ] 

15  */ 


where ( ) {#collection-method} 

The  where  method  filters  the  collection  by  a given  key  / value  pair: 


1 Icol lection  = collect([ 


2 

['product'  => 

1 Desk ' , 

'price'  => 

200]  , 

3 

['product'  => 

’Chair' 

, 'price'  = 

> 100] , 

4 

['product'  => 

1 Bookcase ’ , 1 price 

' =>  150] , 

5 

['product'  => 

1 Door  1 , 

'price'  => 

100]  , 

6 ]); 

7 

8 Ifiltered  = |col lection- >where( ' price ' , 100); 

9 

10  |f i ltered- >al 1 ( ) ; 

11 

12  /* 

13  [ 

['product'  =>  'Chair',  'price'  =>  100], 

15  ['product'  =>  'Door',  'price'  =>  100], 

16  ] 

17  */ 


The  where  method  uses  strict  comparisons  when  checking  item  values.  Use  the  whereLoose  method 
to  filter  using  “loose”  comparisons. 
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whereLoose( ) {#collection-method} 

This  method  has  the  same  signature  as  the  where  method;  however,  all  values  are  compared  using 
“loose”  comparisons. 

whereln( ) {#collection-method} 


The  wherein  method  filters  the  collection  by  a given  key  / value  contained  within  the  given  array. 


1 

$col lection  = collect([ 

2 

['product'  => 

'Desk',  ’price1  =>  200], 

3 

['product'  => 

’Chair',  'price'  =>  100], 

4 

['product'  => 

'Bookcase',  'price'  =>  150], 

5 

['product'  => 

'Door',  'price'  =>  100], 

6 

D; 

7 

8 

$filtered  = $col lection- >whereln( ' price  1 , [150,  200]); 

9 

10 

$ f i ltered- >al 1 ( ) ; 

11 

12 

/* 

13 

[ 

14 

['product'  => 

'Bookcase',  'price'  =>  150], 

15 

['product'  => 

'Desk',  ’price1  =>  200], 

16 

] 

17 

*/ 

The  wherein  method  uses  strict  comparisons  when  checking  item  values.  Use  the  wherelnLoose 
method  to  fdter  using  “loose”  comparisons. 

whereInLoose( ) {#collection-method} 

This  method  has  the  same  signature  as  the  where  I n method;  however,  all  values  are  compared  using 
“loose”  comparisons. 

zip()  {#collection-method} 

The  zip  method  merges  together  the  values  of  the  given  array  with  the  values  of  the  collection  at 
the  corresponding  index: 
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1 $collection  = col lect( [' Chair ' , 'Desk']); 

2 

3 $zipped  = $collection->zip( [100,  200]); 

4 

5 $zipped->all( ) ; 

6 

7 //  [['Chair',  100],  ['Desk',  200]] 
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Introduction 

Laravel  Elixir  provides  a clean,  fluent  API  for  defining  basic  Gulp147  tasks  for  your  Laravel 
application.  Elixir  supports  several  common  CSS  and  JavaScript  pre-processors,  and  even  testing 
tools.  Using  method  chaining,  Elixir  allows  you  to  fluently  define  your  asset  pipeline.  For  example: 

1 el ixir( function(mix)  { 

2 A>  mix . sass( ' app . scss ' ) 

3 A>  . coffee( ' app . coffee ') ; 

4 

5 }); 

If  you’ve  ever  been  confused  about  how  to  get  started  with  Gulp  and  asset  compilation,  you  will 
love  Laravel  Elixir.  However,  you  are  not  required  to  use  it  while  developing  your  application.  You 
are  free  to  use  any  asset  pipeline  tool  you  wish,  or  even  none  at  all. 

Installation  & Setup 

Installing  Node 

Before  triggering  Elixir,  you  must  first  ensure  that  Node.js  is  installed  on  your  machine. 


147http://gulpjs.com 
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1 node  -v 


By  default,  Laravel  Homestead  includes  everything  you  need;  however,  if  you  aren’t  using  Vagrant, 
then  you  can  easily  install  Node  by  visiting  their  download  page148. 

Gulp 

Next,  you’ll  want  to  pull  in  Gulp149  as  a global  NPM  package: 


1 npm  install  --global  gulp 


If  you  use  a version  control  system,  you  may  wish  to  run  the  npm  shrinkwrap  to  lock  your  NPM 
requirements: 

1 npm  shrinkwrap 


Once  you  have  run  this  command,  feel  free  to  commit  the  [npm-shrinkwrap.json] https : //docs . npmjs . com/cl  i/sh: 
into  source  control. 

Laravel  Elixir 

The  only  remaining  step  is  to  install  Elixir!  Within  a fresh  installation  of  Laravel,  you’ll  find  a 
package,  json  file  in  the  root.  Think  of  this  like  your  composer . json  file,  except  it  defines  Node 
dependencies  instead  of  PHP.  You  may  install  the  dependencies  it  references  by  running: 

1 npm  install 


If  you  are  developing  on  a Windows  system  or  you  are  running  your  VM  on  a Windows  host  system, 
you  may  need  to  run  the  npm  install  command  with  the  - -no-bin- links  switch  enabled: 


148http://nodejs.org/download/ 

149http://gulpjs.com 
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1 npm  install  - -no-bin- 1 inks 


Running  Elixir 

Elixir  is  built  on  top  of  Gulp150,  so  to  run  your  Elixir  tasks  you  only  need  to  run  the  gulp  command 
in  your  terminal.  Adding  the  - -production  flag  to  the  command  will  instruct  Elixir  to  minify  your 
CSS  and  JavaScript  files: 


1 //  Run  al 1 tasks  . . . 

2 gulp 

3 

4 //  Run  all  tasks  and  minify  all  CSS  and  JavaScript... 

5 gulp  --production 


Watching  Assets  For  Changes 

Since  it  is  inconvenient  to  run  the  gulp  command  on  your  terminal  after  every  change  to  your  assets, 
you  may  use  the  gulp  watch  command.  This  command  will  continue  running  in  your  terminal  and 
watch  your  assets  for  any  changes.  When  changes  occur,  new  files  will  automatically  be  compiled: 


1 gulp  watch 


Working  With  Stylesheets 

The  gulpfile.  js  file  in  your  project’s  root  directory  contains  all  of  your  Elixir  tasks.  Elixir  tasks 
can  be  chained  together  to  define  exactly  how  your  assets  should  be  compiled. 

Less 

To  compile  Less151  into  CSS,  you  may  use  the  less  method.  The  less  method  assumes  that  your 
Less  files  are  stored  in  resources/assets/less.  By  default,  the  task  will  place  the  compiled  CSS  for 
this  example  in  publ  ic/css/app . css: 

1 5 °http :/ / gulpj  s . com 
151http://lesscss.org/ 


1 

2 

3 

4 

1 

2 

3 

4 

5 

6 

7 

1 

2 

3 

4 

5 

6 

7 

8 

9 

10 


Laravel  Elixir 


301 


el ixir( function(mix)  { 

A>  mix . less( ' app . less 1 ) ; 


}); 

You  may  also  combine  multiple  Less  files  into  a single  CSS  file.  Again,  the  resulting  CSS  will  be 
placed  in  publ  ic/css/app . css: 

el ixir( function(mix)  { 

A>  mix . less(  [ 

A>  ' app . less ' , 

A>  ' control lers . less ' 

A>  ]); 

}); 

If  you  wish  to  customize  the  output  location  of  the  compiled  CSS,  you  may  pass  a second  argument 
to  the  less  method: 

el ixir( function(mix)  { 

A>  mix . less( ' app . less ' , ' publ ic/stylesheets 1 ) ; 


}); 

//  Specifying  a specific  output  filename.  . . 
el ixir( function(mix)  { 

A>  mix . less( 1 app . less 1 , ' publ ic/stylesheets/style . css  1 ) ; 

}); 

Sass 

The  sass  method  allows  you  to  compile  Sass152  into  CSS.  Assuming  your  Sass  files  are  stored  at 
resources/assets/sass,  you  may  use  the  method  like  so: 


152 


'http://sass-  lang.  com/ 
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el ixir( function(mix)  { 

A>  mix . sass( ' app . scss 1 ) ; 


}); 

Again,  like  the  less  method,  you  may  compile  multiple  Sass  files  into  a single  CSS  file,  and  even 
customize  the  output  directory  of  the  resulting  CSS: 

el ixir( function(mix)  { 

A>  mix . sass(  [ 

A>  ' app . scss ' , 

A>  ' control lers . scss ' 

A>  ],  ' publ ic/assets/css ' ) ; 

}); 

Plain  CSS 

If  you  would  just  like  to  combine  some  plain  CSS  stylesheets  into  a single  file,  you  may  use  the 
styles  method.  Paths  passed  to  this  method  are  relative  to  the  resources/assets/css  directory 
and  the  resulting  CSS  will  be  placed  in  public/css/all  .css: 

el ixir( function(mix)  { 

A>  mix . styles(  [ 

A>  ' normal ize . css 1 , 

A>  'main. css' 

A>  ]); 

}); 

Of  course,  you  may  also  output  the  resulting  file  to  a custom  location  by  passing  a second  argument 
to  the  styles  method: 

el ixir( function(mix)  { 

A>  mix . styles( [ 

A>  ' normal ize . css 1 , 

A>  'main. css' 

A>  ],  'public/assets/css'); 

}); 
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Source  Maps 

Source  maps  are  enabled  out  of  the  box.  So,  for  each  file  that  is  compiled  you  will  find  a companion 
*. css. map  file  in  the  same  directory.  This  mapping  allows  you  to  trace  your  compiled  stylesheet 
selectors  back  to  your  original  Sass  or  Less  while  debugging  in  your  browser. 

If  you  do  not  want  source  maps  generated  for  your  CSS,  you  may  disable  them  using  a simple 
configuration  option: 

el ixir . conf ig . sourcemaps  = false; 

el ixir( function(mix)  { 

A>  mix . sass( ' app . scss 1 ) ; 


}); 

Working  With  Scripts 

Elixir  also  provides  several  functions  to  help  you  work  with  your  JavaScript  files,  such  as  compiling 
ECMAScript  6,  compiling  CoffeeScript,  Browserify,  minification,  and  simply  concatenating  plain 
JavaScript  files. 

CoffeeScript 

The  coffee  method  may  be  used  to  compile  CoffeeScript153  into  plain  JavaScript.  The  coffee 
function  accepts  a string  or  array  of  CoffeeScript  files  relative  to  the  resources/assets/coffee 
directory  and  generates  a single  app . js  file  in  the  publ  ic/ js  directory: 

el ixir( function(mix)  { 

A>  mix . coffee( [' app . coffee ' , ' control lers . coffee ']) ; 


}); 

Browserify 

Elixir  also  ships  with  a browserify  method,  which  gives  you  all  the  benefits  of  requiring  modules 
in  the  browser  and  using  ECMAScript  6 and  JSX. 

This  task  assumes  that  your  scripts  are  stored  in  resources/assets/js  and  will  place  the  resulting 
file  in  publ  ic/js/main . js: 

153 


http://coffeescript.org/ 
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el ixir( function(mix)  { 

A>  mix . browseri fy( ' main . js ') ; 


}); 

While  Browserify  ships  with  the  Partialify  and  Babelify  transformers,  you’re  free  to  install  and  add 
more  if  you  wish: 

1 npm  install  aliasify  --save-dev 


elixir. conf ig . js . browserify . transformers . push( { 
A>  name : 'aliasify ' , 

A>  options:  {} 


}); 

el ixir( function(mix)  { 

A>  mix . browseri fy( ' main . js 1 ) ; 


}); 

Babel 


The  babel  method  may  be  used  to  compile  ECMAScript  6 and  7154  and  JSX155  into  plain  JavaScript. 
This  function  accepts  an  array  of  files  relative  to  the  resources/assets/ js  directory,  and  generates 
a single  al  1 . js  file  in  the  publ  ic/js  directory: 

el ixir( function(mix)  { 

A>  mix . babel ( [ 

A>  ' order . js ' , 

A>  ' product . js ' , 

A>  ' react-component . jsx ' 

A>  ]); 

}); 


To  choose  a different  output  location,  simply  specify  your  desired  path  as  the  second  argument. 
The  signature  and  functionality  of  this  method  are  identical  to  mix . scripts( ),  excluding  the  Babel 
compilation. 

154https://babeljs.io/docs/learn-es2015/ 

155https://facebook.github.io/react/docs/jsx-in-depth.html 
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Scripts 

If  you  have  multiple  JavaScript  files  that  you  would  like  to  combine  into  a single  file,  you  may  use 
the  scripts  method. 

The  scripts  method  assumes  all  paths  are  relative  to  the  resources/assets/ js  directory,  and  will 
place  the  resulting  JavaScript  in  public/js/all . js  by  default: 

el ixir( function(mix)  { 

A>  mix . scripts!  [ 

A>  ' jquery . js 1 , 

A>  'app.js' 

A>  ]); 

}); 

If  you  need  to  combine  multiple  sets  of  scripts  into  different  files,  you  may  make  multiple  calls  to 
the  scripts  method.  The  second  argument  given  to  the  method  determines  the  resulting  fde  name 
for  each  concatenation: 

el ixir( function(mix)  { 

A>  mix. scripts! [' app . js ' , 1 control lers . js '] , ' publ ic/js/app . js ' ) 

A>  . scripts! [' forum . js ' , 1 threads . js '] , ' publ ic/js/forum . js 1 ) ; 


}); 

If  you  need  to  combine  all  of  the  scripts  in  a given  directory,  you  may  use  the  scripts  In  method. 
The  resulting  JavaScript  will  be  placed  in  public  /js/all . js: 

el ixir( function(mix)  { 

A>  mix . scriptsln( ' publ ic/js/some/directory ' ); 


}); 

Copying  Files  & Directories 


The  copy  method  may  be  used  to  copy  files  and  directories  to  new  locations.  All  operations  are 
relative  to  the  project’s  root  directory: 
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el ixir( function(mix)  { 

A>  mix . copy( ' vendor/ foo/bar . css ' , ' publ ic/css/bar . css 1 ) ; 


}); 

el ixir( function(mix)  { 

A>  mix . copy ( ' vendor/package/views ' , ' resources/views ' ) ; 


}); 

Versioning  / Cache  Busting 

Many  developers  suffix  their  compiled  assets  with  a timestamp  or  unique  token  to  force  browsers  to 
load  the  fresh  assets  instead  of  serving  stale  copies  of  the  code.  Elixir  can  handle  this  for  you  using 
the  version  method. 

The  version  method  accepts  a file  name  relative  to  the  public  directory,  and  will  append  a unique 
hash  to  the  filename,  allowing  for  cache-busting.  For  example,  the  generated  file  name  will  look 
something  like:  all-16d570a7.css: 

el ixir( function(mix)  { 

A>  mix . version! ' css/al 1 . css ') ; 


}); 

After  generating  the  versioned  file,  you  may  use  Laravel’s  global  el  ixir  PHP  helper  function  within 
your  views  to  load  the  appropriately  hashed  asset.  The  el  ixir  function  will  automatically  determine 
the  name  of  the  hashed  file: 


1 <link  rel="stylesheet"  bref-"{{  el ixir ( ' css/al 1 . css ' ) }}"> 


Versioning  Multiple  Files 

You  may  pass  an  array  to  the  version  method  to  version  multiple  files: 
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el ixir( function(mix)  { 

A>  mix . version( [ ' css/al 1 . css ' , ' js/app . js ' ] ) ; 


}); 

Once  the  files  have  been  versioned,  you  may  use  the  elixir  helper  function  to  generate  links  to  the 
proper  hashed  files.  Remember,  you  only  need  to  pass  the  name  of  the  un-hashed  file  to  the  elixir 
helper  function.  The  helper  will  use  the  un-hashed  name  to  determine  the  current  hashed  version 
of  the  file: 


1 <link  rel  = "stylesheet"  href="{{  el ixir( ' css/al 1 . css ' ) }}"> 

2 

3 <script  src="{{  el ixir( ' js/app . js ' ) }}"> </script> 


BrowserSync 

BrowserSync  automatically  refreshes  your  web  browser  after  you  make  changes  to  your  front-end 
resources.  You  can  use  the  browserSync  method  to  instruct  Elixir  to  start  a BrowserSync  server  when 
you  run  the  gulp  watch  command: 

el ixir( function(mix)  { 

A>  mix . browserSync( ) ; 


}); 

Once  you  run  gulp  watch,  access  your  web  application  using  port  3000  to  enable  browser  syncing: 
http : //homestead  . app : 3000.  If  you’re  using  a domain  other  than  homestead . app  for  local  devel- 
opment, you  may  pass  an  array  of  options156  as  the  first  argument  to  the  browserSync  method: 

el ixir( function(mix)  { 

A>  mix . browserSync ( { 

A>  proxy:  ' project . app ' 

A>  }); 

}); 

156http://www.browsersync.io/docs/options/ 
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Calling  Existing  Gulp  Tasks 

If  you  need  to  call  an  existing  Gulp  task  from  Elixir,  you  may  use  the  task  method.  As  an  example, 
imagine  that  you  have  a Gulp  task  that  simply  speaks  a bit  of  text  when  called: 

gulp . task( 1 speak ' , function!)  { 

A>  var  message  = 'Tea... Earl  Grey... Hot'; 

A> 

A>  gulp . src( ''). pipe(shel 1 ( 1 say  ' + message)); 

}); 

If  you  wish  to  call  this  task  from  Elixir,  use  the  mix . task  method  and  pass  the  name  of  the  task  as 
the  only  argument  to  the  method: 

el ixir( function(mix)  { 

A>  mix . task( 1 speak ') ; 


}); 

Custom  Watchers 

If  you  need  to  register  a watcher  to  run  your  custom  task  each  time  some  files  are  modified,  pass  a 
regular  expression  as  the  second  argument  to  the  task  method: 

el ixir( function(mix)  { 

A>  mix . task( ' speak ' , ' app/**/* ■ php ' ) ; 


}); 

Writing  Elixir  Extensions 


If  you  need  more  flexibility  than  Elixir’s  task  method  can  provide,  you  may  create  custom  Elixir 
extensions.  Elixir  extensions  allow  you  to  pass  arguments  to  your  custom  tasks.  For  example,  you 
could  write  an  extension  like  so: 
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//  File:  elixir-extensions . js 

var  gulp  = require( ' gulp 1 ) ; 

var  shell  = require( ' gulp-shel 1 ' ) ; 

var  Elixir  = require( ' laravel -el ixir 1 ) ; 

var  Task  = Elixir. Task; 

Elixir. extend( ' speak 1 , function(message)  { 

A>  new  Task( 1 speak  1 , function()  { 

A>  return  gulp . src( ''). pipe(shel 1 ( 1 say  1 + message)); 

A>  }); 

}); 

//  mix . speak( ' Hello  World'); 

That’s  it!  Notice  that  your  Gulp-specific  logic  should  be  placed  within  the  function  passed  as  the 
second  argument  to  the  Task  constructor.  You  may  either  place  this  at  the  top  of  your  Gulpfile, 
or  instead  extract  it  to  a custom  tasks  file.  For  example,  if  you  place  your  extensions  in  el ixir - 
extensions . js,  you  may  require  the  file  from  your  main  Gulpfile  like  so: 

//  File:  Gulpfile . js 

var  elixir  = require( ' laravel -el ixir 1 ) ; 
require( 1 ./elixir-extensions' ) 
el ixir( function(mix)  { 

A>  mix.speak( 'Tea,  Earl  Grey,  Hot'); 


}); 

Custom  Watchers 

If  you  would  like  your  custom  task  to  be  re-triggered  while  running  gulp  watch,  you  may  register 
a watcher: 
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1 new  Task( ' speak  1 , function()  { 

2 A>  return  gulp . src( 1 1 ). pipe(shel 1 (' say 

3 

4 }) 

5 . watch( ' . /app/** 1 ) ; 


+ message)); 


Encryption 

• Configuration 

• Basic  Usage 

Configuration 

Before  using  Laravel’s  encrypter,  you  should  set  the  key  option  of  your  conf  ig/app . php  configu- 
ration file  to  a 32  character,  random  string.  If  this  value  is  not  properly  set,  all  values  encrypted  by 
Laravel  will  be  insecure. 

Basic  Usage 

Encrypting  A Value 

You  may  encrypt  a value  using  the  Crypt  facade.  All  encrypted  values  are  encrypted  using 
OpenSSL  and  the  AES-256-CBC  cipher.  Furthermore,  all  encrypted  values  are  signed  with  a message 
authentication  code  (MAC)  to  detect  any  modifications  to  the  encrypted  string. 

For  example,  we  may  use  the  encrypt  method  to  encrypt  a secret  and  store  it  on  an  Eloquent  model: 


1 < ?php 

2 

3 namespace  App\Http\Control lers; 

4 

5 use  Crypt; 

6 use  App\User; 

7 use  Illuminate\Http\Request; 

8 use  App\Http\Controllers\Controller; 

9 


10 

class  UserController  extends  Controller 

11 

{ 

12 

/** 

13 

* Store  a 

secret  message  for  the  user 

14 

* 

15 

* §param 

Request  $request 

16 

* §param 

int  Sid 

17 

* §return  Response 

18 

*/ 
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19 

20 
21 


public  function  storeSecret( Request  Srequest,  $id) 


$user  = User :: findOrFai 1 (Sid) ; 


22 

23 


Suser- > f i 1 1 ( [ 


24 

25 

26 


'secret'  =>  Crypt: :encrypt($request->secret) 
] ) - >save( ) ; 


27  } 


o 


Note:  Encrypted  values  are  passed  through  serialize  during  encryption,  which  allows  for 
“encryption”  of  objects  and  arrays.  Thus,  non-PHP  clients  receiving  encrypted  values  will 
need  to  unserial  ize  the  data. 


Decrypting  A Value 

Of  course,  you  may  decrypt  values  using  the  decrypt  method  on  the  Crypt  facade.  If  the  value  can 

not  be  properly  decrypted,  such  as  when  the  MAC  is  invalid,  an  1 1 1 urn  i nate\Contracts  \Encry  pt  i on  \DecryptExcepi 

will  be  thrown: 

1 use  Illuminate\Contracts\Encryption\DecryptException; 

2 

3 try  { 

4 Sdecrypted  Crypt:  decrypt(SencryptedValue) ; 

5 } catch  (DecryptException  $e)  { 


6  // 

7 } 


Errors  & Logging 

• Introduction 

• Configuration 

• The  Exception  Handler  A>  - Report  Method  A>  - Render  Method 

• HTTP  Exceptions  A>  - Custom  HTTP  Error  Pages 

• Logging 

Introduction 

When  you  start  a new  Laravel  project,  error  and  exception  handling  is  already  configured  for  you. 
In  addition,  Laravel  is  integrated  with  the  Monolog157  logging  library,  which  provides  support  for  a 
variety  of  powerful  log  handlers. 

Configuration 

Error  Detail 

The  amount  of  error  detail  your  application  displays  through  the  browser  is  controlled  by  the 
debug  configuration  option  in  your  conf  ig/app . php  configuration  file.  By  default,  this  configuration 
option  is  set  to  respect  the  APP_DEBUG  environment  variable,  which  is  stored  in  your  . env  file. 

For  local  development,  you  should  set  the  APP_DEBUG  environment  variable  to  true.  In  your 
production  environment,  this  value  should  always  be  false. 

Log  Modes 

Out  of  the  box,  Laravel  supports  single,  daily,  syslog  and  error  log  logging  modes.  For  example, 
if  you  wish  to  use  daily  log  files  instead  of  a single  file,  you  should  simply  set  the  log  value  in  your 
conf  ig/app . php  configuration  file: 


1 ' log ' =>  'daily' 


157https://github.com/Seldaek/monolog 
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Custom  Monolog  Configuration 

If  you  would  like  to  have  complete  control  over  how  Monolog  is  configured  for  your  application,  you 
may  use  the  application’s  conf  igureMonologllsing  method.  You  should  place  a call  to  this  method 
in  your  bootstrap/app . php  file  right  before  the  $app  variable  is  returned  by  the  file: 


1 $app->conf igureMonologllsing( function($monolog)  { 

$monolog->pushHandler( . . . ); 

3 }); 

4 

5 return  Sapp; 


The  Exception  Handler 

All  exceptions  are  handled  by  the  App\Exceptions\Handler  class.  This  class  contains  two  methods: 
report  and  render.  We’ll  examine  each  of  these  methods  in  detail. 

The  Report  Method 

The  report  method  is  used  to  log  exceptions  or  send  them  to  an  external  service  like  BugSnag158. 
By  default,  the  report  method  simply  passes  the  exception  to  the  base  class  where  the  exception  is 
logged.  However,  you  are  free  to  log  exceptions  however  you  wish. 

For  example,  if  you  need  to  report  different  types  of  exceptions  in  different  ways,  you  may  use  the 
PHP  instanceof  comparison  operator: 


1 /** 

2 * Report  or  log  an  exception . 

3 * 

4 * This  is  a great  spot  to  send  exceptions  to  Sentry,  Bugsnag,  etc. 

5 * 

6 * §param  \Exception  $e 

7 * §return  void 

8 V 

9 public  function  report( Exception  $e) 

10  { 

11  if  ($e  instanceof  CustomException)  { 

12  // 

13  } 


158 


shttps://bugsnag.com 
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14 

15  return  parent :: report($e) ; 

16  } 


Ignoring  Exceptions  By  Type 

The  $dontReport  property  of  the  exception  handler  contains  an  array  of  exception  types  that  will 
not  be  logged.  By  default,  exceptions  resulting  from  404  errors  are  not  written  to  your  log  files.  You 
may  add  other  exception  types  to  this  array  as  needed. 

The  Render  Method 

The  render  method  is  responsible  for  converting  a given  exception  into  an  HTTP  response  that 
should  be  sent  back  to  the  browser.  By  default,  the  exception  is  passed  to  the  base  class  which 
generates  a response  for  you.  However,  you  are  free  to  check  the  exception  type  or  return  your  own 
custom  response: 

1 /** 

2 * Render  an  exception  into  an  HTTP  response . 

3 * 

4 * §param  \Illuminate\Http\Request  $request 

5 * §param  \Exception  $e 

6 * §return  \Illuminate\Http\Response 

7 V 

8 public  function  render($request,  Exception  $e) 

9 { 

10  if  ($e  instanceof  CustomException)  { 

11  return  response( )- >view( ' errors . custom ' , [],  500); 

12  } 

13 

14  return  parent: : render ($request,  $e); 

15  } 


HTTP  Exceptions 


Some  exceptions  describe  HTTP  error  codes  from  the  server.  For  example,  this  may  be  a “page  not 
found”  error  (404),  an  “unauthorized  error”  (401)  or  even  a developer  generated  500  error.  In  order 
to  generate  such  a response  from  anywhere  in  your  application,  use  the  following: 
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1 abort(404); 


The  abort  method  will  immediately  raise  an  exception  which  will  be  rendered  by  the  exception 
handler.  Optionally,  you  may  provide  the  response  text: 

1 abort(403,  'Unauthorized  action.'); 


This  method  may  be  used  at  any  time  during  the  request’s  lifecycle. 

Custom  HTTP  Error  Pages 

Laravel  makes  it  easy  to  return  custom  error  pages  for  various  HTTP  status  codes.  For  example, 
if  you  wish  to  customize  the  error  page  for  404  HTTP  status  codes,  create  a resources/views/er- 
rors/404 . blade . php.  This  file  will  be  served  on  all  404  errors  generated  by  your  application. 

The  views  within  this  directory  should  be  named  to  match  the  HTTP  status  code  they  correspond 
to. 

Logging 

The  Laravel  logging  facilities  provide  a simple  layer  on  top  of  the  powerful  Monolog159  library.  By 
default,  Laravel  is  configured  to  create  daily  log  files  for  your  application  which  are  stored  in  the 
storage/ logs  directory.  You  may  write  information  to  the  logs  using  the  Log  facade: 


1 < ?php 

2 

3 namespace  App\Http\Control lers; 

4 

5 use  Log; 

6 use  App\User; 

7 use  App\Http\Controllers\Controller; 

8 

9 class  UserController  extends  Controller 

10  { 

11  /** 

12  * Show  the  profile  for  the  given  user. 


159 


’http  ://github . com/seldaek/monolog 
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13  * 

14  * @param  int  $id 

15  * §return  Response 

16  */ 

17  public  function  showProf i le($id) 

18  { 

19  Log :: info( 1 Showing  user  profile  for  user:  ' . $ i d ) ; 

20 

return  view( 1 user . prof i le ' , [ user'  =>  User  : f indOrFai 1 ($id) ] ) ; 

22  } 

23  } 


The  logger  provides  the  eight  logging  levels  defined  in  RFC  5424160:  emergency,  alert,  critical,  error, 
warning,  notice,  info  and  debug. 


1 Log: : emergency ($error); 

2 Log : : alert($error ) ; 

3 Log :: critical ($error) ; 

4 Log :: error ($error) ; 

5 Log : : warning($error) ; 

6 Log : : notice($error) ; 

7 Log : : info($error) ; 

8 Log : : debug($error) ; 


Contextual  Information 

An  array  of  contextual  data  may  also  be  passed  to  the  log  methods.  This  contextual  data  will  be 
formatted  and  displayed  with  the  log  message: 

1 Log :: info( ' User  failed  to  login.',  ['id'  =>  $user->idj); 


Accessing  The  Underlying  Monolog  Instance 

Monolog  has  a variety  of  additional  handlers  you  may  use  for  logging.  If  needed,  you  may  access 
the  underlying  Monolog  instance  being  used  by  Laravel: 

160 


’http  ://tools . ietf.org/html/rfc5424 
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1 Smonolog  = Log : : getMonolog( ) ; 


Events 


• Introduction 

• Registering  Events  / Listeners 

• Defining  Events 

• Defining  Listeners  A>  - Queued  Event  Listeners 

• Firing  Events 

• Broadcasting  Events  A>  - Configuration  A>  - Marking  Events  For  Broadcast  A>  - Broadcast 
Data  A>  - Event  Broadcasting  Customizations  A>  - Consuming  Event  Broadcasts 

• Event  Subscribers 

Introduction 

Laravel’s  events  provides  a simple  observer  implementation,  allowing  you  to  subscribe  and  listen 
for  events  in  your  application.  Event  classes  are  typically  stored  in  the  app/Events  directory,  while 
their  listeners  are  stored  in  app/Listeners. 

Registering  Events  / Listeners 

The  EventServiceProvider  included  with  your  Laravel  application  provides  a convenient  place  to 
register  all  event  listeners.  The  listen  property  contains  an  array  of  all  events  (keys)  and  their 
listeners  (values).  Of  course,  you  may  add  as  many  events  to  this  array  as  your  application  requires. 
For  example,  let’s  add  our  PodcastWasPurchased  event: 


1 /** 

2 * The  event  listener  mappings  for  the  application. 

3 * 

4 * §var  array 

5 V 

6 protected  Slisten  [ 

7 ' App\Events\PodcastWasPurchased ' =>  [ 

1 App\Listeners\Emai lPurchaseConf irmation ' , 

9 ], 

10  ]; 
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Generating  Event  / Listener  Classes 

Of  course,  manually  creating  the  files  for  each  event  and  listener  is  cumbersome.  Instead,  simply 
add  listeners  and  events  to  your  EventServiceProvider  and  use  the  event : generate  command. 
This  command  will  generate  any  events  or  listeners  that  are  listed  in  your  EventServiceProvider. 
Of  course,  events  and  listeners  that  already  exist  will  be  left  untouched: 


1  php  artisan  event : generate 


Registering  Events  Manually 

Typically,  events  should  be  registered  via  the  EventServiceProvider  $listen  array;  however,  you 
may  also  register  events  manually  with  the  event  dispatcher  using  either  the  Event  facade  or  the 
1 1 luminate\Contracts\Events\Dispatcher  contract  implementation: 

1 /** 

2 * Register  any  other  events  for  your  application. 

3 * 

4 * §param  \Illuminate\Contracts\Events\Dispatcher  $events 

5 * §return  void 

6 V 

7 public  function  boot( DispatcherContract  $events) 

8 { 

9 parent :: boot($events) ; 

10 

11  $events- > 1 isten( 1 event . name  1 , function  ($foo,  $bar)  { 

12  // 

13  }); 

14  } 


Wildcard  Event  Listeners 

You  may  even  register  listeners  using  the  * as  a wildcard,  allowing  you  to  catch  multiple  events  on 
the  same  listener.  Wildcard  listeners  receive  the  entire  event  data  array  as  a single  argument: 
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1 $events- > 1 isten( ' event , function  (array  $data)  { 

2 // 

3 }); 


Defining  Events 

An  event  class  is  simply  a data  container  which  holds  the  information  related  to  the  event.  For 
example,  let’s  assume  our  generated  PodcastWasPurchased  event  receives  an  Eloquent  ORM  object: 

1 < ?php 

2 

3 namespace  App\Events; 

4 

5 use  App\Podcast; 

6 use  App\Events\Event; 

7 use  1 1 luminate\Queue\Ser ial izesModels; 

8 

9  class  PodcastWasPurchased  extends  Event 

10  { 

11  use  Serial izesModels; 

12 

13  public  $podcast; 

14 

15  /** 

16  * Create  a new  event  instance. 

17  * 

18  * @param  Podcast  $ podcast 

19  * §return  void 

20  */ 

21  public  function  construct(Podcast  $podcast) 

22  { 

23  $this- >podcast  = $podcast; 

24  } 

25  } 


As  you  can  see,  this  event  class  contains  no  logic.  It  is  simply  a container  for  the  Podcast  object  that 
was  purchased.  The  Serial  izesModels  trait  used  by  the  event  will  gracefully  serialize  any  Eloquent 
models  if  the  event  object  is  serialized  using  PHP’s  serialize  function. 
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Defining  Listeners 

Next,  let’s  take  a look  at  the  listener  for  our  example  event.  Event  listeners  receive  the  event  instance 
in  their  handle  method.  The  event : generate  command  will  automatically  import  the  proper  event 
class  and  type-hint  the  event  on  the  handle  method.  Within  the  handle  method,  you  may  perform 
any  logic  necessary  to  respond  to  the  event. 


1 < ?php 

2 

3 namespace  App\Listeners; 

4 

5 use  App\Events\PodcastWasPurchased; 

6 use  1 1 luminate\Queue\InteractsWithQueue; 

7 use  1 1 luminate\Contracts\Queue\ShouldQueue; 

8 

9  class  Emai lPurchaseConf irmation 

10  { 

11  /** 

12  * Create  the  event  listener. 

13  * 

14  * §return  void 

15  */ 

16  public  function  constructQ 

17  { 

18  // 

19  } 

20 

21  /** 

22  * Handle  the  event. 

23  * 

24  * §param  PodcastWasPurchased  $event 

25  * §return  void 

26  */ 

public  function  handle(PodcastWasPurchased  $event) 

28  { 

29  //  Access  the  podcast  using  $event- > podcast . . . 

30  } 

31  } 


Your  event  listeners  may  also  type-hint  any  dependencies  they  need  on  their  constructors.  All 
event  listeners  are  resolved  via  the  Laravel  service  container,  so  dependencies  will  be  injected 
automatically: 
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1 use  Illuminate\Contracts\Mail\Mailer; 

2 

3 public  function  construct(Mailer  $mailer) 

4 { 

5 $this- >mai ler  = $mailer; 

6 } 


Stopping  The  Propagation  Of  An  Event 

Sometimes,  you  may  wish  to  stop  the  propagation  of  an  event  to  other  listeners.  You  may  do  so  by 
returning  false  from  your  listener’s  handle  method. 

Queued  Event  Listeners 

Need  to  queue  an  event  listener?  It  couldn’t  be  any  easier.  Simply  add  the  ShouldQueue  interface  to 
the  listener  class.  Listeners  generated  by  the  event : generate  Artisan  command  already  have  this 
interface  imported  into  the  current  namespace,  so  you  can  use  it  immediately: 


1 < ?php 

2 

3 namespace  App\Listeners; 

4 

5 use  App\Events\PodcastWasPurchased; 

6 use  1 1 luminate\Queue\InteractsWithQueue; 

7 use  1 1 luminate\Contracts\Queue\ShouldQueue; 

8 

9  class  Emai lPurchaseConf irmation  implements  ShouldQueue 

10  { 

11  // 

12  } 


That’s  it!  Now,  when  this  listener  is  called  for  an  event,  it  will  be  queued  automatically  by  the  event 
dispatcher  using  Laravel’s  queue  system.  If  no  exceptions  are  thrown  when  the  listener  is  executed 
by  the  queue,  the  queued  job  will  automatically  be  deleted  after  it  has  processed. 

Manually  Accessing  The  Queue 

If  you  need  to  access  the  underlying  queue  job’s  delete  and  release  methods  manually,  you  may 
do  so.  The  1 1 luminate\Queue\InteractsWithQueue  trait,  which  is  imported  by  default  on  generated 
listeners,  gives  you  access  to  these  methods: 
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1 < ?php 

2 

3 namespace  App\Listeners; 

4 

5 use  App\Events\PodcastWasPurchased; 

6 use  1 1 luminate\Queue\InteractsWithQueue; 

7 use  1 1 luminate\Contracts\Queue\ShouldQueue; 

8 

9  class  Emai lPurchaseConf irmation  implements  ShouldQueue 

10  { 

11  use  InteractsWithQueue; 

12 

public  function  handle(PodcastWasPurchased  $event) 

14  { 

15  if  (true)  { 

16  $this- >release(30) ; 

17  } 

18  } 

19  } 


Firing  Events 

To  fire  an  event,  you  may  use  the  Event  facade,  passing  an  instance  of  the  event  to  the  fire  method. 
The  fire  method  will  dispatch  the  event  to  all  of  its  registered  listeners: 

1 < ?php 

2 

3 namespace  App\Http\Control lers; 

4 

5 use  Event; 

6 use  App\Podcast; 

7 use  App\Events\PodcastWasPurchased; 

8 use  App\Http\Controllers\Controller; 

9 

10  class  UserController  extends  Controller 

11  { 

12  /** 

13  * Show  the  profile  for  the  given  user. 

14  * 

15 


* §param  int  $userld 


Events 


325 


16  * §param  int  $podcastId 

17  * §return  Response 

18  */ 

19  public  function  purchasePodcast($userId,  Spodcastld) 

20  { 

$podcast  = Podcast :: findOrFai 1 (Spodcastld) ; 

22 

23  //  Purchase  podcast  logic. . . 

24 

Event  :fire(new  PodcastWasPurchased($podcast) ) ; 

26  } 

27  } 


Alternatively,  you  may  use  the  global  event  helper  function  to  fire  events: 
1 event(new  PodcastWasPurchased(Spodcast) ) ; 


Broadcasting  Events 

In  many  modern  web  applications,  web  sockets  are  used  to  implement  real-time,  live-updating  user 
interfaces.  When  some  data  is  updated  on  the  server,  a message  is  typically  sent  over  a websocket 
connection  to  be  handled  by  the  client. 

To  assist  you  in  building  these  types  of  applications,  Laravel  makes  it  easy  to  “broadcast”  your  events 
over  a websocket  connection.  Broadcasting  your  Laravel  events  allows  you  to  share  the  same  event 
names  between  your  server-side  code  and  your  client-side  JavaScript  framework. 

Configuration 

All  of  the  event  broadcasting  configuration  options  are  stored  in  the  conf ig/broadcasting . php 
configuration  file.  Laravel  supports  several  broadcast  drivers  out  of  the  box:  Pusher161,  Redis,  and  a 
log  driver  for  local  development  and  debugging.  A configuration  example  is  included  for  each  of 
these  drivers. 

Broadcast  Prerequisites 

The  following  dependencies  are  needed  for  event  broadcasting: 

161 


https://pusher.com 
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• Pusher:  pusher/pusher-php-server  ~2.0 

• Redis:  predi  s/pred  is  ~1.0 

Queue  Prerequisites 

Before  broadcasting  events,  you  will  also  need  to  configure  and  run  a queue  listener.  All  event 
broadcasting  is  done  via  queued  jobs  so  that  the  response  time  of  your  application  is  not  seriously 
affected. 

Marking  Events  For  Broadcast 

To  inform  Laravel  that  a given  event  should  be  broadcast,  implement  the  1 1 luminate\Contracts\Broadcasting\Sh' 
interface  on  the  event  class.  The  Shout dBroadcast  interface  requires  you  to  implement  a single 
method:  broadcastOn.  The  broadcastOn  method  should  return  an  array  of  “channel”  names  that 
the  event  should  be  broadcast  on: 


1 < ?php 

2 

3 namespace  App\Events; 

4 

5 use  App\User; 

6 use  App\Events\Event; 

7 use  1 1 luminate\Queue\Ser ial izesModels; 

8 use  1 1 luminate\Contracts\Broadcasting\ShouldBroadcast; 

9 

10  class  ServerCreated  extends  Event  implements  ShouldBroadcast 

11  { 

12  use  Serial izesModels; 

13 

14  public  $user; 

15 

16  /** 

17  * Create  a new  event  instance. 

18  * 

19  * §return  void 

20  */ 

public  function  construct(User  $user) 

22  { 

23  $this->user  = $user; 

24  } 

25 

26  /** 

* Get  the  channels  the  event  should  be  broadcast  on. 

28  * 
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29  * §return  array 

30  */ 

31  public  function  broadcastOn( ) 

32  { 

return  [ 'user. ' . $this- >user- > id] ; 

34  } 

35  } 


Then,  you  only  need  to  fire  the  event  as  you  normally  would.  Once  the  event  has  been  fired,  a 
queued  job  will  automatically  broadcast  the  event  over  your  specified  broadcast  driver. 


Broadcast  Data 

When  an  event  is  broadcast,  all  of  its  public  properties  are  automatically  serialized  and  broadcast  as 
the  event’s  payload,  allowing  you  to  access  any  of  its  public  data  from  your  JavaScript  application. 
So,  for  example,  if  your  event  has  a single  public  $user  property  that  contains  an  Eloquent  model, 
the  broadcast  payload  would  be: 

i { 

"user"  : { 

3 "id":  1, 

4 "name":  "Jonathan  Banks" 

5 

6 } 

7 } 


However,  if  you  wish  to  have  even  more  fine-grained  control  over  your  broadcast  payload,  you  may 
add  a broadcastWith  method  to  your  event.  This  method  should  return  the  array  of  data  that  you 
wish  to  broadcast  with  the  event: 


1 /** 

2 * Get  the  data  to  broadcast . 

3 * 

4 * §return  array 

5 V 

6 public  function  broadcastWith( ) 

7 { 
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return  ['user'  =>  $this->user->id] ; 

9 } 


Event  Broadcasting  Customizations 

Customizing  The  Event  Name 

By  default,  the  broadcast  event  name  will  be  the  fully  qualified  class  name  of  the  event.  So,  if  the 
event’s  class  name  is  App \E vents  \ServerCreated , the  broadcast  event  would  be  App \E vents  \ServerCreated . 
You  can  customize  this  broadcast  event  name  using  by  defining  a broadcastAs  method  on  your  event 
class: 


1 /** 

2 * Get  the  broadcast  event  name. 

3 * 

4 * § return  string 

5 V 

6 public  function  broadcastAs( ) 

7 { 

return  ' app . server -created  1 2 3 4 5 6 7 ; 

9 } 


Customizing  The  Queue 

By  default,  each  event  to  be  broadcast  is  placed  on  the  default  queue  for  the  default  queue  connection 
in  your  queue . php  configuration  file.  You  may  customize  the  queue  used  by  the  event  broadcaster 
by  adding  an  onQueue  method  to  your  event  class.  This  method  should  return  the  name  of  the  queue 
you  wish  to  use: 


1 /** 

2 * Set  the  name  of  the  queue  the  event  should  be  placed  on. 

3 * 

4 * @return  string 

5 */ 

6 public  function  onQueue() 

7 { 
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return  ' your-queue-name ' ; 

9 } 


Consuming  Event  Broadcasts 

Pusher 

You  may  conveniently  consume  events  broadcast  using  the  Pusher162  driver  using  Pusher’s  JavaScript 
SDK.  For  example,  let’s  consume  the  App\Events\ServerCreated  event  from  our  previous  examples: 

1 this. pusher  = new  Pusher (' pusher-key ') ; 

2 

3 this . pusherChannel  = this . pusher . subscribe( ' user . ' + USER_ID); 

4 

5 this . pusherChannel . bind( ' App\\Events\\ServerCreated ' , function(message)  { 

6 console . log(message . user ) ; 

7 }); 


Redis 

If  you  are  using  the  Redis  broadcaster,  you  will  need  to  write  your  own  Redis  pub/sub  consumer 
to  receive  the  messages  and  broadcast  them  using  the  websocket  technology  of  your  choice.  For 
example,  you  may  choose  to  use  the  popular  Socket.io163  library  which  is  written  in  Node. 

Using  the  socket,  io  and  ioredis  Node  libraries,  you  can  quickly  write  an  event  broadcaster  to 
publish  all  events  that  are  broadcast  by  your  Laravel  application: 


1 var  app  = require( 1 http '). createServer (handler ) ; 

2 var  io  = require( ' socket . io ') (app) ; 

3 

4 var  Redis  = require( ' ioredis ') ; 

5 var  redis  = new  RedisQ; 

6 

7  app . 1 isten(6001 , functionQ  { 

console . log( ' Server  is  running!'); 

9 1); 


162https://pusher.com 

163http://socket.io 
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10 

11  function  handler(req,  res)  { 

12  res.writeHead(200); 

13  res . end( ' ' ) ; 

14  } 

15 

16  io . on( ' connection ' , function(socket)  { 

17  // 

18  }); 

19 

20  redis . psubscr ibe( ' * ' , function(err , count)  { 

21  // 

22  }); 

23 

24  redis . on( ' pmessage 1 , function(subscribed,  channel,  message)  { 

25  message  = JSON . parse(message) ; 

io . emit(channel  + + message . event,  message . data) ; 

27  }); 


Event  Subscribers 

Event  subscribers  are  classes  that  may  subscribe  to  multiple  events  from  within  the  class  itself, 
allowing  you  to  define  several  event  handlers  within  a single  class.  Subscribers  should  define  a 
subscribe  method,  which  will  be  passed  an  event  dispatcher  instance: 


1 < ?php 

2 

3 namespace  App\Listeners; 

4 

5 class  UserEventListener 

6 { 

7 /** 

* Handle  user  login  events. 

9 */ 

10  public  function  onllserLogin($event)  {} 

11 

12  /** 

13  * Handle  user  logout  events. 

14  */ 

15  public  function  onllserl_ogout($event)  {} 
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16 

17  /** 

18  * Register  the  listeners  for  the  subscriber . 

19  * 

* §param  1 1 luminate\Events\Dispatcher  $events 

21  */ 

22  public  function  subscribe($events) 

23  { 

24  $events->listen( 

25  ' App\Events\UserLoggedIn ' , 

26  ' App\Listeners\UserEventListener@onUserLogin ' 

27  ); 

28 

29  $events- > 1 isten( 

30  ' App\Events\UserLoggedOut ' , 

31  ' App\Listeners\UserEventListener@onUserLogout ' 

32  ); 

33  } 

34 

35  } 


Registering  An  Event  Subscriber 

Once  the  subscriber  has  been  defined,  it  may  be  registered  with  the  event  dispatcher.  You  may 
register  subscribers  using  the  $subscribe  property  on  the  EventServiceProvider.  For  example, 
let’s  add  the  UserEventListener. 


1 < ?php 

2 

3 namespace  App\Providers; 

4 

5 use  1 1 luminate\Contracts\Events\Dispatcher  as  DispatcherContract; 

6 use  1 1 luminate\Foundation\Support\Providers\EventServiceProvider  as  ServiceProvi \ 

7 der ; 

8 

9 class  EventServiceProvider  extends  ServiceProvider 

10  { 

11  /** 

12  * The  event  listener  mappings  for  the  application. 

13  * 

14 


* §var  array 
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16  protected  $listen  [ 

17  // 

18  ]; 

19 

20  /** 

21  * The  subscriber  classes  to  register 

22  * 

23  * §var  array 

24  */ 

25  protected  $subscribe  = [ 

26  1 App\Listeners\UserEventListener 1 

27  ]; 

28  } 
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Introduction 

Laravel  provides  a powerful  filesystem  abstraction  thanks  to  the  wonderful  Flysystem164  PHP 
package  by  Frank  de  Jonge.  The  Laravel  Flysystem  integration  provides  simple  to  use  drivers 
for  working  with  local  filesystems,  Amazon  S3,  and  Rackspace  Cloud  Storage.  Even  better,  it’s 
amazingly  simple  to  switch  between  these  storage  options  as  the  API  remains  the  same  for  each 
system. 

Configuration 

The  filesystem  configuration  file  is  located  at  config/filesystems.php.  Within  this  file  you  may 
configure  all  of  your  “disks”.  Each  disk  represents  a particular  storage  driver  and  storage  location. 
Example  configurations  for  each  supported  driver  is  included  in  the  configuration  file.  So,  simply 
modify  the  configuration  to  reflect  your  storage  preferences  and  credentials. 

Of  course,  you  may  configure  as  many  disks  as  you  like,  and  may  even  have  multiple  disks  that  use 
the  same  driver. 

The  Local  Driver 

When  using  the  local  driver,  note  that  all  file  operations  are  relative  to  the  root  directory  defined 
in  your  configuration  file.  By  default,  this  value  is  set  to  the  storage/app  directory.  Therefore,  the 
following  method  would  store  a file  in  storage/app/f  i le . txt: 

1 Storage: :disk( ' local ' )->put( ' file.txt' , ’Contents'); 


164https://github.com/thephpleague/flysystem 
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Other  Driver  Prerequisites 

Before  using  the  S3  or  Rackspace  drivers,  you  will  need  to  install  the  appropriate  package  via 
Composer: 

• Amazon  S3:  league/f Iysystem-aws-s3-v3  ~1.0 

• Rackspace:  league/f lysystem-rackspace  ~1.0 

Basic  Usage 

Obtaining  Disk  Instances 

The  Storage  facade  may  be  used  to  interact  with  any  of  your  configured  disks.  For  example,  you 
may  use  the  put  method  on  the  facade  to  store  an  avatar  on  the  default  disk.  If  you  call  methods 
on  the  Storage  facade  without  first  calling  the  disk  method,  the  method  call  will  automatically  be 
passed  to  the  default  disk: 

1 < ?php 

2 

3 namespace  App\Http\Control lers; 

4 

5 use  Storage; 

6 use  1 1 luminate\Http\Request; 

7 use  App\Http\Controllers\Controller; 

8 

9 class  UserController  extends  Controller 

10  { 

11  /** 

12  * Update  the  avatar  for  the  given  user. 

13  * 

14  * §param  Request  $request 

15  * §param  int  $id 

16  * §return  Response 

17  */ 

18  public  function  updateAvatar( Request  $request,  $id) 

19  { 

20  $user  = User : : f indOrFai 1 ($id) ; 

21 

Storage : : put( 

23  ' avatars/ $user- > id, 

24  f i le_get_contents($request->  f i le( ' avatar ' ) - >getRealPath( ) ) 

25  ); 

26 


1 
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27  } 


When  using  multiple  disks,  you  may  access  a particular  disk  using  the  disk  method  on  the  Storage 
facade.  Of  course,  you  may  continue  to  chain  methods  to  execute  methods  on  the  disk: 

1 $disk  = Storage :: disk( ' s3 ') ; 

2 

3 Scontents  = Storage :: disk( ' local ')- >get( 1 fi le . jpg ' ) 


Retrieving  Files 

The  get  method  may  be  used  to  retrieve  the  contents  of  a given  file.  The  raw  string  contents  of  the 
file  will  be  returned  by  the  method: 

1 Scontents  = Storage :: get( ' fi le . jpg ') ; 


The  exists  method  may  be  used  to  determine  if  a given  file  exists  on  the  disk: 
1 Sexists  = Storage :: disk( ’ s3 ') ->exists( ' fi le . jpg ') ; 


File  Meta  Information 

The  size  method  may  be  used  to  get  the  size  of  the  file  in  bytes: 
1 Ssize  = Storage :: size( ' fi lei . jpg ') ; 


The  lastModi  f ied  method  returns  the  UNIX  timestamp  of  the  last  time  the  file  was  modified: 
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1 $time  = Storage :: lastModi fied( ' fi lei . jpg ') ; 


Storing  Files 

The  put  method  may  be  used  to  store  a file  on  disk.  You  may  also  pass  a PHP  resource  to 
the  put  method,  which  will  use  Flysystem’s  underlying  stream  support.  Using  streams  is  greatly 
recommended  when  dealing  with  large  files: 


1 Storage :: put( ' fi le . jpg ' , Scontents); 

2 

3 Storage: :put( ' file. jpg' , $resource); 


The  copy  method  may  be  used  to  copy  an  existing  file  to  a new  location  on  the  disk: 


1 Storage :: copy( ' old/fi lei . jpg ' , ' new/filel . jpg ' ) ; 


The  move  method  may  be  used  to  rename  or  move  an  existing  file  to  a new  location: 


1 Storage :: move( ' old/fi lei . jpg ' , ' new/f i lei . jpg ' ) ; 


Prepending  / Appending  To  Files 

The  prepend  and  append  methods  allow  you  to  easily  insert  content  at  the  beginning  or  end  of  a file: 


1 Storage :: prepend( ' fi le . log ' , 'Prepended  Text'); 

2 

3 Storage :: append( ' fi le . log ' , 'Appended  Text'); 
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Deleting  Files 

The  delete  method  accepts  a single  filename  or  an  array  of  files  to  remove  from  the  disk: 

1 Storage :: delete( ' fi le . jpg ') ; 

2 

3 Storage :: delete( [ ' fi lei . jpg ' , 1 f i le2 . jpg  1 ] ) ; 


Directories 

Get  All  Files  Within  A Directory 

The  files  method  returns  an  array  of  all  of  the  files  in  a given  directory  If  you  would  like  to  retrieve 
a list  of  all  files  within  a given  directory  including  all  sub-directories,  you  may  use  the  allFiles 
method: 


1 $files  = Storage: : files($directory) ; 

2 

3 $files  = Storage: :allFiles($directory); 


Get  All  Directories  Within  A Directory 

The  directories  method  returns  an  array  of  all  the  directories  within  a given  directory.  Addition- 
ally, you  may  use  the  al  1 Directories  method  to  get  a list  of  all  directories  within  a given  directory 
and  all  of  its  sub-directories: 

1 $directories  = Storage :: directories($directory ) ; 

2 

3 //  Recursive. . . 

4 $directories  = Storage :: al IDirector i es($di rectory ) ; 


Create  A Directory 

The  makeDirectory  method  will  create  the  given  directory,  including  any  needed  sub-directories: 
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1 Storage: : makeDirectory($directory ) ; 


Delete  A Directory 

Finally,  the  deleteDi rectory  may  be  used  to  remove  a directory,  including  all  of  its  files,  from  the 
disk: 

1 Storage: : deleteDirectory($directory ) ; 


Custom  Filesystems 

Laravel’s  Flysystem  integration  provides  drivers  for  several  “drivers”  out  of  the  box;  however, 
Flysystem  is  not  limited  to  these  and  has  adapters  for  many  other  storage  systems.  You  can  create  a 
custom  driver  if  you  want  to  use  one  of  these  additional  adapters  in  your  Laravel  application. 

In  order  to  set  up  the  custom  filesystem  you  will  need  to  create  a service  provider  such  as 
DropboxServiceProvider.  In  the  provider’s  boot  method,  you  may  use  the  Storage  facade’s  extend 
method  to  define  the  custom  driver: 


1 < ?php 

2 

3 namespace  App\Providers; 

4 

5 use  Storage; 

6 use  League\Flysystem\Filesystem; 

7 use  Dropbox\Cl ient  as  DropboxCl ient; 

8 use  1 1 luminate\Support\ServiceProvider ; 

9 use  League\Flysystem\Dropbox\DropboxAdapter ; 

10 

11  class  DropboxServiceProvider  extends  ServiceProvider 

12  { 

13  /** 

14  * Perform  post-registration  booting  of  services. 

15  * 

16 

17 

18 


* §return  void 
*/ 

public  function  boot() 
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19  { 

Storage :: extend (' dropbox ' , function($app,  $config)  { 

21  $client  = new  DropboxCl ient( 

22  $conf ig [ ' accessToken ' ] , $conf ig [ cl ientldenti f ier ' ] 

23  ); 

24 

return  new  Filesystem(new  DropboxAdapter($client) ) ; 

26  }); 

27  } 

28 

29  /** 

30  * Register  bindings  in  the  container . 

31  * 

32  * §return  void 

33  */ 

34  public  function  registerQ 

35  { 

36  // 

37  } 

38  } 


The  first  argument  of  the  extend  method  is  the  name  of  the  driver  and  the  second  is  a Closure 
that  receives  the  $app  and  $config  variables.  The  resolver  Closure  must  return  an  instance  of 
League\Flysystem\Filesystem.  The  $config  variable  contains  the  values  defined  in  config/- 
f i lesystems . php  for  the  specified  disk. 

Once  you  have  created  the  service  provider  to  register  the  extension,  you  may  use  the  dropbox  driver 
in  your  con  fig/filesystem,  php  configuration  file. 


Hashing 

• Introduction 

• Basic  Usage 

Introduction 

The  Laravel  Hash  facade  provides  secure  Bcrypt  hashing  for  storing  user  passwords.  If  you  are  using 
the  AuthController  controller  that  is  included  with  your  Laravel  application,  it  will  automatically 
use  Bcrypt  for  registration  and  authentication. 

Bcrypt  is  a great  choice  for  hashing  passwords  because  its  “work  factor”  is  adjustable,  which  means 
that  the  time  it  takes  to  generate  a hash  can  be  increased  as  hardware  power  increases. 

Basic  Usage 

You  may  hash  a password  by  calling  the  make  method  on  the  Hash  facade: 


1 < ?php 

2 

3 namespace  App\Http\Control lers; 

4 

5 use  Hash; 

6 use  App\User; 

7 use  1 1 luminate\Http\Request; 

8 use  App\Http\Controllers\Controller; 

9 

10  class  UserController  extends  Controller 

11  { 

12  /** 

13  * Update  the  password  for  the  user. 

14  * 

15  * §param  Request  $request 

16  * §param  int  $id 

17  * §return  Response 

18  */ 

public  function  updatePassword( Request  $request,  $id) 

20  { 

21  $user  = User  : f indOrFai 1 ($id) ; 
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22 

23  //  Validate  the  new  password  length. . . 

24 

25  $user- > f i 1 1 ( [ 

'password'  =>  Hash : : make($request- >newPassword) 
] ) - >save( ) ; 

28  } 

29  } 


Alternatively,  you  may  also  use  the  global  bcrypt  helper  function: 


1 bcrypt( ' plain-text 1 ) ; 


Verifying  A Password  Against  A Hash 

The  check  method  allows  you  to  verify  that  a given  plain-text  string  corresponds  to  a given  hash. 
However,  if  you  are  using  the  AuthController  included  with  Laravel,  you  will  probably  not  need 
to  use  this  directly,  as  the  included  authentication  controller  automatically  calls  this  method: 


1 if  (Hash :: check( ' plain-text ' , ShashedPassword) ) { 
//  The  passwords  match. . . 

3 } 


Checking  If  A Password  Needs  To  Be  Rehashed 

The  needsRehash  function  allows  you  to  determine  if  the  work  factor  used  by  the  hasher  has  changed 
since  the  password  was  hashed: 


1 if  (Hash : : needsRehash ($hashed) ) { 

$hashed  = Hash  : make( 1 plain-text ') ; 

3 } 


Helper  Functions 

• Introduction 

• Available  Methods 

Introduction 

Laravel  includes  a variety  of  “helper”  PHP  functions.  Many  of  these  functions  are  used  by  the 
framework  itself;  however,  you  are  free  to  use  them  in  your  own  applications  if  you  find  them 
convenient. 

Available  Methods 

<style>  A>  .collection-method-list  > p { A>  column-count:  3;  -moz-column-count:  3;  -webkit- 
column-count:  3;  A>  column-gap:  2em;  -moz-column-gap:  2em;  -webkit-column-gap:  2em;  A>  } A> 
A>  .collection- method-list  a { A>  display:  block;  A>  } 

</style> 

Arrays 

<div  class=”collection-method-list”  markdown=”l”>  array_add  array_collapse  array_divide  array_- 
dot  array_except  array_first  array_flatten  array_forget  array  _get  array_has  array  _only  array_pluck 
array_pull  array_set  array_sort  array_sort_recursive  array _where  head  last  </div> 


Paths 

<div  class=”collection-method-list”  markdown=”l”>  app_path  base_path  config_path  database_- 
path  elixir  public_path  storage_path  </div> 

Strings 

<div  class=”collection-method-list”  markdown=”l”>  camel_case  class_basename  e ends_with  snake_- 
case  str_limit  starts_with  str_contains  str_finish  str_is  str_plural  str_random  str_singular  str_slug 
studly_case  trans  trans_choice  </div> 
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URLs 

<div  class= ’’collection-method-list”  markdown=”l”>  action  asset  secure_asset  route  url  </div> 

Miscellaneous 

<div  class= ’’collection-method-list”  markdown=”l”>  auth  back  bcrypt  collect  config  csrf_field  csrf_- 
token  dd  dispatch  env  event  factory  method_field  old  redirect  request  response  session  value  view 
with  </div> 

Method  Listing 

<style>  A>  #collection-method  code  { A>  font-size:  14px;  A>  } A>  A>  #collection-method:not(.first- 
collection-method)  { A>  margin-top:  50px;  A>  } 

</style> 

Arrays 

array_add( ) {#collection-method  .first-collection-method} 

The  array_add  function  adds  a given  key  / value  pair  to  the  array  if  the  given  key  doesn’t  already 
exist  in  the  array: 

1 $array  = array_add( [ ' name ' =>  'Desk'],  'price',  100); 

2 

3 //  ['name'  =>  'Desk',  'price'  =>  100] 


array_collapse( ) {#collection-method} 

The  array_col  lapse  function  collapse  an  array  of  arrays  into  a single  array: 


1 $array  = array_col lapse( [ [1 , 2,  3],  [4,  5,  6],  [7,  8,  9]]); 

2 

3 //  [1,  2,  3,  4,  5,  6,  7,  8,  9] 
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array_divide( ) {#collection-method} 

The  array_divide  function  returns  two  arrays,  one  containing  the  keys,  and  the  other  containing 
the  values  of  the  original  array: 


1 list(|keys,  lvalues)  = array_divide( [ ' name ' =>  'Desk']); 

2 

3 //  Ikeys : [ ' name ' ] 

4 

5 //  lvalues:  ['Desk'] 


array_dot( ) {#collection-method} 

The  array_dot  function  flattens  a multi-dimensional  array  into  a single  level  array  that  uses  “dot” 
notation  to  indicate  depth: 

1 larray  = array_dot( [ ' foo ' =>  ['bar'  =>  ' baz ' ] ] ) ; 

2 

3 //  ['foo. bar'  =>  'baz']; 


array_except( ) {#collection-method} 

The  array_except  function  removes  the  given  key  / value  pairs  from  the  array: 


1 larray  = ['name'  =>  'Desk',  'price1  =>  100]; 

2 

3 larray  = array_except(|array , ['price']); 

4 

5 //  ['name'  =>  'Desk'] 


array_f irst( ) {#collection-method} 

The  array_first  function  returns  the  first  element  of  an  array  passing  a given  truth  test: 
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1 $array  = [100,  200,  300] ; 

2 

3 lvalue  = array_f irst($array,  function  ($key,  lvalue)  { 

4 return  lvalue  >=  150; 

5 }); 

6 

7 //  200 


A default  value  may  also  be  passed  as  the  third  parameter  to  the  method.  This  value  will  be  returned 
if  no  value  passes  the  truth  test: 

1 lvalue  = array_f irst(|array,  Icallback,  Idefault); 


array_f latten  ( ) {#collection-method} 

The  array_f  latten  function  will  flatten  a multi-dimensional  array  into  a single  level. 

1 larray  = ['name'  =>  'Joe',  ’languages’  =>  [’PHP’,  ’Ruby’]]; 

2 

3 larray  = array_f latten(|array ) ; 

4 

5 //  ['Joe’,  ’PHP',  ’Ruby']; 


array _forget( ) {#collection-method} 

The  array_forget  function  removes  a given  key  / value  pair  from  a deeply  nested  array  using  “dot” 
notation: 

1 larray  = [’products’  =>  ['desk'  =>  ['price'  =>  100]]]; 

2 

3 array_forget(|array , ' products . desk ’) ; 

4 

5 //  ['products’  =>  []] 
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array_get( ) {#COlleCtion-method} 

The  array_get  function  retrieves  a value  from  a deeply  nested  array  using  “dot”  notation: 

1 $array  = ['products'  =>  ['desk'  =>  ['price'  =>  100]]]; 

2 

3 lvalue  = array_get($array,  ' products . desk ') ; 

4 

5 //  [ ' price ' =>  100] 


The  array_get  function  also  accepts  a default  value,  which  will  be  returned  if  the  specific  key  is  not 
found: 


1 lvalue  = array_get(|array,  ' names . john ' , 'default'); 


array_has( ) {#collection-method} 

The  array_has  function  checks  that  a given  item  exists  in  an  array  using  “dot”  notation: 

1 larray  = ['products'  =>  ['desk'  =>  ['price'  =>  100]]]; 

2 

3 IhasDesk  = array_has(|array,  ' products . desk ') ; 

4 

5 //  true 


array_only( ) {#collection-method} 

The  array_only  function  will  return  only  the  specified  key  / value  pairs  from  the  given  array: 

1 larray  = ['name'  =>  'Desk',  'price'  =>  100,  'orders'  =>  10]; 

2 

3 larray  = array_only(|array , ['name',  'price']); 

4 

5 //  ['name'  =>  'Desk',  'price'  =>  100] 
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array_pluck( ) {#collection-method} 


The  array_pluck  function  will  pluck  a list  of  the  given  key  / value  pairs  from  the  array: 


1 

$array  = [ 

2 

['developer'  =>  ['id'  => 

1,  'name'  =>  'Taylor']], 

3 

['developer'  =>  ['id'  => 

2,  'name'  =>  'Abigail']], 

4 

]; 

5 

6 

$array  = array_pluck($array, 

' developer . name ' ) ; 

7 

8 

//  ['Taylor',  'Abigail']; 

You  may  also  specify  how  you  wish  the  resulting  list  to  be  keyed: 


1 $array  = array_pluck($array,  ' developer . name ' , ' developer . id ') ; 

2 

3 //  [1  =>  'Taylor',  2 =>  'Abigail']; 


array_prepend ( ) {#collection-method} 

The  array_prepend  function  will  push  an  item  onto  the  beginning  of  an  array: 

1 $array  = ['one',  'two',  'three',  'four']; 

2 

3 $array  = array_prepend($array , 'zero'); 

4 

5 //  $array:  ['zero',  'one',  ’two',  'three',  'four'] 


array_pull()  {#collection-method} 

The  array_pul  1 function  returns  and  removes  a key  / value  pair  from  the  array: 


Helper  Functions 


348 


1 $array  = ['name'  =>  'Desk',  'price1  =>  100]; 

2 

3 $name  = array_pul 1 ($array,  'name'); 

4 

5 //  Iname:  Desk 

6 

7 //  $array:  ['price'  =>  100] 


array_set( ) {#collection-method} 

The  array_set  function  sets  a value  within  a deeply  nested  array  using  “dot”  notation: 

1 $array  = ['products'  =>  ['desk'  =>  ['price'  =>  100]]]; 

2 

3 array_set($array,  ' products . desk . price ' , 200); 

4 

5 //  ['products'  =>  ['desk'  =>  ['price'  =>  200]]] 


array_sort( ) {#collection-method} 

The  array_sort  function  sorts  the  array  by  the  results  of  the  given  Closure: 


1 $array  = [ 

[ ' name ' =>  ' Desk ' ] , 

[ ' name ' =>  ' Chair ' ] , 

4 ]; 

5 

6 $array  = array_values(array_sort($array , function  (lvalue)  { 

7 return  lvalue [' name '] ; 


8 

})); 

9 

10 

/* 

11 

[ 

12 

['name'  => 

'Chair' ] 

13 

[ ' name ' => 

’ Desk  1 ] , 

14 

] 
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15  */ 


array_sort_recursive( ) {#collection-method} 


The  array_sort_recursive  function  recursively  sorts  the  array  using  the  sort  function: 


1 

$array 

= [ 

2 

[ 

3 

1 Roman ' , 

4 

’Taylor’ , 

5 

'Li' , 

6 

], 

7 

[ 

8 

' PHP ' , 

9 

' Ruby ' , 

10 

' JavaScript ' , 

11 

1, 

12 

]; 

13 

14 

$array 

= array_sort_recursive($array) ; 

15 

16 

/* 

17 

[ 

18 

[ 

19 

'Li ' , 

20 

' Roman ' , 

21 

' Taylor ' , 

22 

L 

23 

[ 

24 

' JavaScript ' , 

25 

'PHP' , 

26 

' Ruby ' , 

27 

] 

28 

]; 

29 

*/ 

array_where( ) {#collection-method} 

The  array_where  function  filters  the  array  using  the  given  Closure: 
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1 $array  = [100,  '200',  300,  '400',  500]; 

2 

3 $array  = array_where($array , function  ($key,  lvalue)  { 

4 return  is_string( lvalue) ; 

5 }); 

6 

7 //  [1  =>  200,  3 =>  400] 


head()  {#collection-method} 

The  head  function  simply  returns  the  first  element  in  the  given  array: 

1 larray  = [100,  200,  300] ; 

2 

3 Ifirst  = head(|array ) ; 

4 

5 //  100 


iast()  {#collection-method} 

The  last  function  returns  the  last  element  in  the  given  array: 


1 larray  = [100,  200,  300] ; 

2 

3 Hast  = last(|array ) ; 

4 

5 //  300 


Paths 

app_path( ) {#collection-method} 

The  app_path  function  returns  the  fully  qualified  path  to  the  app  directory: 
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1 $path  = app_path(); 


You  may  also  use  the  app_path  function  to  generate  a fully  qualified  path  to  a given  file  relative  to 
the  application  directory: 


1 $path  = app_path( ' Http/Control lers/Control ler . php 1 ) ; 


base_path( ) {#collection-method} 

The  base_path  function  returns  the  fully  qualified  path  to  the  project  root: 
1 $path  = base_path(); 


You  may  also  use  the  base_path  function  to  generate  a fully  qualified  path  to  a given  file  relative  to 
the  application  directory: 

1 $path  = base_path( 1 vendor/bin ') ; 


conf ig_path( ) {#collection-method} 

The  conf  ig_path  function  returns  the  fully  qualified  path  to  the  application  configuration  directory: 
1 $path  = conf ig_path( ) ; 


database_path ( ) {#collection-method} 

The  database_path  function  returns  the  fully  qualified  path  to  the  application’s  database  directory: 
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1 $path  = database_path( ) ; 


elixir( ) {#collection-method} 

The  elixir  function  gets  the  path  to  the  versioned  Elixir  file: 
1 el ixir($f i le) ; 


pubi ic_path( ) {#collection-method} 

The  publ ic_path  function  returns  the  fully  qualified  path  to  the  public  directory: 
1 $path  = publ ic_path( ) ; 


storage_path( ) {#collection-method} 

The  storage_path  function  returns  the  fully  qualified  path  to  the  storage  directory: 
1 $path  = storage_path( ) ; 


You  may  also  use  the  storage_path  function  to  generate  a fully  qualified  path  to  a given  file  relative 
to  the  storage  directory: 

1 $path  = storage_path( ' app/f i le . txt ' ) ; 


Strings 


camel_case( ) {#collection-method} 

The  camel_case  function  converts  the  given  string  to  camelCase: 
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1 $camel  = camel_case( ' foo_bar ' ) ; 

2 

3 //  fooBar 


class_basename( ) {#collection-method} 

The  class_basename  returns  the  class  name  of  the  given  class  with  the  class’  namespace  removed: 


1 $class  = class_basename( ' Foo\Bar\Baz ' ) ; 

2 

3 //  Baz 


e( ) {#collection-method} 

The  e function  runs  html entities  over  the  given  string: 

1 echo  e( ' <html> foo</html> ' ) ; 

2 

3 //  &lt  html&gt ; foo&lt; /html&gt; 

ends_with( ) {#collection-method} 

The  ends_with  function  determines  if  the  given  string  ends  with  the  given  value: 

1 lvalue  = ends_with( 1 This  is  my  name',  'name'); 

2 

3 //  true 

snake_case( ) {#collection-method} 

The  snake_case  function  converts  the  given  string  to  snake_case: 
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1 $snake  = snake_case( ' fooBar ' ) ; 

2 

3 //  foo_bar 


str_l imit( ) {#collection-method} 

The  str_l  imit  function  limits  the  number  of  characters  in  a string.  The  function  accepts  a string  as 
its  first  argument  and  the  maximum  number  of  resulting  characters  as  its  second  argument: 

1 lvalue  = str_l imit( 1 The  PHP  framework  for  web  artisans.',  7); 

2 

3 //  The  PHP. . . 


starts_with( ) {#collection-method} 

The  starts_with  function  determines  if  the  given  string  begins  with  the  given  value: 


1 lvalue  = starts_with( ' This  is  my  name',  'This'); 

2 

3 //  true 


str_contains( ) {#collection-method} 


The  str_contains  function  determines  if  the  given  string  contains  the  given  value: 


1 

lvalue  = str_contains( 1 This  is  my  name’, 

’ my ' ) ; 

2 

3 

//  true 

str_f inish( ) {#collection-method} 

The  str_f  inish  function  adds  a single  instance  of  the  given  value  to  a string: 
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1 Istring  = str_finish( ' this/string  ' , 

2 

3 //  this/string/ 


str_is( ) {#collection-method} 


The  str_is  function  determines  if  a given  string  matches  a given  pattern.  Asterisks  may  be  used  to 
indicate  wildcards: 


1 

lvalue  = 

str_is( ' foo* ' , 

' foobar ' ) ; 

2 

3 

//  true 

4 

5 

lvalue  = 

str_is( ' baz* ' , 

' foobar ' ) ; 

6 

7 

//  false 

str_plural  ( ) {#collection-method} 

The  str_plural  function  converts  a string  to  its  plural  form.  This  function  currently  only  supports 
the  English  language: 

1 Iplural  = str_plural ( ' car  ' ) ; 

2 

3 //  cars 

4 

5 Iplural  = str_plural ( ' chi  Id ' ) ; 

6 

7 //  children 


You  may  provide  an  integer  as  a second  argument  to  the  function  to  retrieve  the  singular  or  plural 
form  of  the  string: 
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1 

Iplural  = str_plural ( ' chi  Id ' , 

2); 

2 

3 

//  children 

4 

5 

Iplural  = str_plural ( ' chi  Id ' , 

i); 

6 

7 

//  child 

str_random( ) {#collection-method} 

The  str_random  function  generates  a random  string  of  the  specified  length: 
1 $string  = str_random(40) ; 


str_singular( ) {#collection-method} 

The  str_singular  function  converts  a string  to  its  singular  form.  This  function  currently  only 
supports  the  English  language: 

1 Ssingular  = str_singular ( ' cars ' ) ; 

2 

3 //  car 


str_slug( ) {#collection-method} 

The  str_slug  function  generates  a URL  friendly  “slug”  from  the  given  string: 


1 $title  = str_slug( "Laravel  5 Framework", 

2 

3 //  laravel -5- framework 
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studly_case( ) {#collection-method} 

The  studly_case  function  converts  the  given  string  to  StudlyCase: 


1 lvalue  = studly_case( ' foo_bar 1 ) ; 

2 

3 //  FooBar 


trans( ) {#collection-method} 

The  trans  function  translates  the  given  language  line  using  your  localization  files: 
1 echo  trans( ' val idation . required ') : 


trans_choice( ) {#collection-method} 

The  trans_choice  function  translates  the  given  language  line  with  inflection: 
1 lvalue  = trans_choice( ' foo . bar  1 , Icount); 


URLs 

action( ) {#collection-method} 

The  action  function  generates  a URL  for  the  given  controller  action.  You  do  not  need  to  pass 
the  full  namespace  to  the  controller.  Instead,  pass  the  controller  class  name  relative  to  the 
App\Http\Control  lers  namespace: 

1 |url  = action( ' HomeControl ler@getlndex ' ) ; 


If  the  method  accepts  route  parameters,  you  may  pass  them  as  the  second  argument  to  the  method: 
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1 $url  = action( ' UserControl ler§prof i le ' , ['id'  =>  1]); 

asset ( ) {#collection-method} 

Generate  a URL  for  an  asset  using  the  current  scheme  of  the  request  (HTTP  or  HTTPS): 
1 $url  = asset( ' img/photo . jpg ' ) ; 


secure_asset( ) {#collection-method} 

Generate  a URL  for  an  asset  using  HTTPS: 

1 echo  secure_asset( ' foo/bar . zip ' , $title,  $attributes  = []); 

route ( ) {#collection-method} 

The  route  function  generates  a URL  for  the  given  named  route: 

1 $url  = route( ' routeName ') ; 

If  the  route  accepts  parameters,  you  may  pass  them  as  the  second  argument  to  the  method: 
1 $url  = route( 1 routeName 1 , [’id1  =>  1]); 


uri ( ) {#collection-method} 

The  url  function  generates  a fully  qualified  URL  to  the  given  path: 
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1 echo  ur 1 (' user/prof i le ') ; 

2 

3 echo  ur 1 (' user/prof i le ' , [1]); 


If  no  path  is  provided,  a Illuminate\Routing\UrlGenerator  instance  is  returned: 

1 echo  ur 1 ( ) - >current( ) ; 

2 echo  ur 1 ( ) - > ful 1 ( ) ; 

3 echo  ur 1 ( ) - >previous( ) ; 


Miscellaneous 

auth()  {#collection-method} 

The  auth  function  returns  an  authenticator  instance.  You  may  use  it  instead  of  the  Auth  facade  for 
convenience: 

1 $user  = auth( ) - >user( ) ; 


back()  {#collection-method} 

The  back( ) function  generates  a redirect  response  to  the  user’s  previous  location: 
1 return  back(); 


bcrypto  {#collection-method} 

The  bcrypt  function  hashes  the  given  value  using  Bcrypt.  You  may  use  it  as  an  alternative  to  the 
Hash  facade: 


Helper  Functions 


360 


1 $password  = bcrypt( 1 my -secret -password ' ) ; 


col lect( ) {#collection-method} 

The  collect  function  creates  a collection  instance  from  the  supplied  items: 
1 $col lection  = col lect( [ ' taylor 1 , 'abigail']); 


configO  {#collection-method} 

The  con  fig  function  gets  the  value  of  a configuration  variable.  The  configuration  values  may  be 
accessed  using  “dot”  syntax,  which  includes  the  name  of  the  file  and  the  option  you  wish  to  access. 
A default  value  may  be  specified  and  is  returned  if  the  configuration  option  does  not  exist: 

1 lvalue  = conf ig( ' app . timezone ' ) ; 

2 

3 lvalue  = conf ig( ' app . timezone ' , Idefault); 


The  con  fig  helper  may  also  be  used  to  set  configuration  variables  at  runtime  by  passing  an  array 
of  key  / value  pairs: 


1 conf ig( [ 1 app . debug  1 =>  true]); 


csrf_f ield( ) {#collection-method} 

The  csrf_field  function  generates  an  HTML  hidden  input  field  containing  the  value  of  the  CSRF 
token.  For  example,  using  Blade  syntax: 

1 { ! ! csr f_f ield( ) ! ! } 
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csrf_token( ) {#collection-method} 

The  csrf_token  function  retrieves  the  value  of  the  current  CSRF  token: 
1 $token  = csrf_token( ) ; 


dd( ) {#collection-method} 

The  dd  function  dumps  the  given  variable  and  ends  execution  of  the  script: 

1 dd( lvalue); 


dispatch( ) {#collection-method} 

The  dispatch  function  pushes  a new  job  onto  the  Laravel  job  queue: 
1 dispatch(new  App\Jobs\SendEmai Is) ; 


env( ) {#collection-method} 

The  env  function  gets  the  value  of  an  environment  variable  or  returns  a default  value: 


1 

$env  = env( 

APP_ENV 

); 

2 

3 

//  Return  a 

default 

value  if  the  variable  doesn't  exist... 

4 

$env  = env( 

APP_ENV 

, ' production ' ) ; 

event( ) {#collection-method} 

The  event  function  dispatches  the  given  event  to  its  listeners: 
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1 event(new  UserRegistered($user ) ) ; 


factory ( ) {#collection-method} 

The  factory  function  creates  a model  factory  builder  for  a given  class,  name,  and  amount.  It  can  be 
used  while  testing  or  seeding: 

1 $user  = factory (App\User :: class) - >make( ) ; 


method_f ield( ) {#collection-method} 


The  method_field  function  generates  an  HTML  hidden  input  field  containing  the  spoofed  value  of 
the  form’s  HTTP  verb.  For  example,  using  Blade  syntax: 


1 

<form  method="POST"> 

2 

{!!  method_field( ' delete  1 ) 

H 

3 

</form> 

oid( ) {#collection-method} 


The  old  function  retrieves  an  old  input  value  flashed  into  the  session: 


1 

lvalue  = old( 

value ' ) 

/ 

2 

3 

lvalue  = old( 

value ' , 

' default 1 ) ; 

redirect( ) {#collection-method} 


The  redirect  function  returns  an  instance  of  the  redirector  to  do  redirects: 


Helper  Functions 


363 


1 return  redirect( ' /home ' ) ; 


request( ) {#collection-method} 

The  request  function  returns  the  current  request  instance  or  obtains  an  input  item: 


1 Irequest  = requestQ; 

2 

3 lvalue  = request( ' key ' , Idefault  = null) 


response( ) {#collection-method} 

The  response  function  creates  a response  instance  or  obtains  an  instance  of  the  response  factory: 

1 return  response( ' Hel lo  World' , 200,  $headers); 

2 

3 return  response( ) - > json( [ ' foo ' =>  'bar'],  200,  Iheaders); 


session( ) {#collection-method} 

The  session  function  may  be  used  to  get  / set  a session  value: 
1 lvalue  = session( ' key ' ) ; 


You  may  set  values  by  passing  an  array  of  key  / value  pairs  to  the  function: 
1 session( [' chairs ' =>  7,  'instruments'  =>  3]); 


The  session  store  will  be  returned  if  no  value  is  passed  to  the  function: 
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1 lvalue  = session( ) - >get( ' key ' ) ; 

2 

3 session( ) - >put( ' key ' , lvalue); 


value( ) {#collection-method} 

The  value  function’s  behavior  will  simply  return  the  value  it  is  given.  However,  if  you  pass  a Closure 
to  the  function,  the  Closure  will  be  executed  then  its  result  will  be  returned: 

1 lvalue  = value( function( ) { return  'bar';  }); 


view()  {#collection-method} 

The  v i ew  function  retrieves  a view  instance: 


1 return  view( ' auth . login ') ; 


with()  {#collection-method} 

The  with  function  returns  the  value  it  is  given.  This  function  is  primarily  useful  for  method  chaining 
where  it  would  otherwise  be  impossible: 

1 lvalue  = with(new  Foo) - >work( ) ; 
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Introduction 

Laravel’s  localization  features  provide  a convenient  way  to  retrieve  strings  in  various  languages, 
allowing  you  to  easily  support  multiple  languages  within  your  application. 

Language  strings  are  stored  in  files  within  the  resources/ lang  directory.  Within  this  directory  there 
should  be  a subdirectory  for  each  language  supported  by  the  application: 

1 /resources 
/lang 
/en 

4 messages. php 

5 /es 

6 messages. php 


All  language  files  simply  return  an  array  of  keyed  strings.  For  example: 


1 < ?php 

2 

3 return  [ 

4 'welcome'  =>  'Welcome  to  our  application' 

5 ]; 


Configuring  The  Locale 

The  default  language  for  your  application  is  stored  in  the  conf ig/app . php  configuration  file.  Of 
course,  you  may  modify  this  value  to  suit  the  needs  of  your  application.  You  may  also  change  the 
active  language  at  runtime  using  the  setLocale  method  on  the  App  facade: 
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1 Route :: get( ' welcome/{ locale} ' , function  ($locale)  { 
App  : setLocale($ locale ) ; 

3 

4 // 

5 }); 


You  may  also  configure  a “fallback  language”,  which  will  be  used  when  the  active  language  does  not 
contain  a given  language  line.  Like  the  default  language,  the  fallback  language  is  also  configured  in 
the  config/app.  php  configuration  file: 


1 ' fal lback_locale ' =>  'en', 


Basic  Usage 

You  may  retrieve  lines  from  language  files  using  the  trans  helper  function.  The  trans  method 
accepts  the  file  and  key  of  the  language  line  as  its  first  argument.  For  example,  let’s  retrieve  the 
language  line  welcome  in  the  resources/lang/messages . php  language  file: 

1 echo  trans( 1 messages . welcome  1 ) ; 


Of  course  if  you  are  using  the  Blade  templating  engine,  you  may  use  the  { { } } syntax  to  echo  the 
language  line: 


1 {{  trans( 1 messages . welcome ’ ) }} 


If  the  specified  language  line  does  not  exist,  the  trans  function  will  simply  return  the  language 
line  key.  So,  using  the  example  above,  the  trans  function  would  return  messages. welcome  if  the 
language  line  does  not  exist. 

Replacing  Parameters  In  Language  Lines 

If  you  wish,  you  may  define  place-holders  in  your  language  lines.  All  place-holders  are  prefixed 
with  a : . For  example,  you  may  define  a welcome  message  with  a place-holder  name: 
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1 'welcome'  =>  'Welcome,  : name 1 , 


To  replace  the  place-holders  when  retrieving  a language  line,  pass  an  array  of  replacements  as  the 
second  argument  to  the  trans  function: 

1 echo  trans( 1 messages . welcome  1 , ['name'  =>  'Dayle']); 


Pluralization 

Pluralization  is  a complex  problem,  as  different  languages  have  a variety  of  complex  rules  for 
pluralization.  By  using  a “pipe”  character,  you  may  distinguish  a singular  and  plural  form  of  a 
string: 

1 'apples'  =>  'There  is  one  apple  I There  are  many  apples', 


Then,  you  may  then  use  the  trans_choice  function  to  retrieve  the  line  for  a given  “count”.  In  this 
example,  since  the  count  is  greater  than  one,  the  plural  form  of  the  language  line  is  returned: 

1 echo  trans_choice( ' messages . apples ' , 10); 


Since  the  Laravel  translator  is  powered  by  the  Symfony  Translation  component,  you  may  create 
even  more  complex  pluralization  rules: 

1 'apples'  =>  '{0}  There  are  none  I [1,19]  There  are  some  I [20, Inf ] There  are  many', 


Overriding  Vendor  Language  Files 

Some  packages  may  ship  with  their  own  language  files.  Instead  of  hacking  the  package’s  core  files 
to  tweak  these  lines,  you  may  override  them  by  placing  your  own  files  in  the  resources/ lang/ven- 
dor/{package}/{ locale}  directory. 
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So,  for  example,  if  you  need  to  override  the  English  language  lines  in  messages . php  for  a package 
named  skyri  m/hearth  fire,  you  would  place  a language  file  at:  resources/ 1 ang/vendor/hearth - 
f ire/en/messages . php.  In  this  file  you  should  only  define  the  language  lines  you  wish  to  override. 
Any  language  lines  you  don’t  override  will  still  be  loaded  from  the  package’s  original  language  files. 
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Introduction 

Laravel  provides  a clean,  simple  API  over  the  popular  SwiftMailer165  library.  Laravel  provides  drivers 
for  SMTP,  Mailgun,  Mandrill,  Amazon  SES,  PHP’s  mail  function,  and  sendmail,  allowing  you  to 
quickly  get  started  sending  mail  through  a local  or  cloud  based  service  of  your  choice. 

Driver  Prerequisites 

The  API  based  drivers  such  as  Mailgun  and  Mandrill  are  often  simpler  and  faster  than  SMTP  servers. 
All  of  the  API  drivers  require  that  the  Guzzle  HTTP  library  be  installed  for  your  application.  You 
may  install  Guzzle  to  your  project  by  adding  the  following  line  to  your  composer . json  file: 

1 "guzzlehttp/guzzle" : "~5 . 3 I ~6 . 0" 


Mailgun  Driver 


To  use  the  Mailgun  driver,  first  install  Guzzle,  then  set  the  driver  option  in  your  conf  ig/mai  1 . php 
configuration  file  to  mailgun.  Next,  verify  that  your  conf ig/services . php  configuration  file 
contains  the  following  options: 


1 

'mailgun'  =>  [ 

2 

'domain'  => 

'your-mailgun-domain' , 

3 

'secret'  => 

' your-mai lgun-key ' , 

4 

L 

1 6 5http :/ / swiftmailer.  org 
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Mandrill  Driver 

To  use  the  Mandrill  driver,  first  install  Guzzle,  then  set  the  driver  option  in  your  conf  ig/mai  1 . php 
configuration  file  to  mandrill.  Next,  verify  that  your  conf ig/services.  php  configuration  file 
contains  the  following  options: 


1 ' mandr i 11'  =>  [ 

'secret'  =>  ' your-mandr i 1 1 -key  ' , 

3 ], 


SES  Driver 

To  use  the  Amazon  SES  driver,  install  the  Amazon  AWS  SDK  for  PHP.  You  may  install  this  library 
by  adding  the  following  line  to  your  composer . json  file’s  require  section: 

1 "aws/aws-sdk-php" : "~3.0" 


Next,  set  the  driver  option  in  your  conf  ig/mai  1 .php  configuration  file  to  ses.  Then,  verify  that 
your  conf  ig/services . php  configuration  file  contains  the  following  options: 


1 

'ses'  =>  [ 

2 

'key'  => 

' your-ses-key ' , 

3 

' secret ' 

=>  ' your-ses-secret ' , 

4 

' region ' 

=>  ' ses-region ' , //  e.g.  us-east-1 

5 

], 

Sending  Mail 

Laravel  allows  you  to  store  your  e-mail  messages  in  views.  For  example,  to  organize  your  e-mails, 
you  could  create  an  emails  directory  within  your  resources/views  directory: 

To  send  a message,  use  the  send  method  on  the  Mail  facade.  The  send  method  accepts  three 
arguments.  First,  the  name  of  a view  that  contains  the  e-mail  message.  Secondly,  an  array  of  data 
you  wish  to  pass  to  the  view.  Fastly,  a Closure  callback  which  receives  a message  instance,  allowing 
you  to  customize  the  recipients,  subject,  and  other  aspects  of  the  mail  message: 
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1 

<?php 

2 

3 

namespace  App\Http\Control lers; 

4 

5 

use 

Mail; 

6 

use 

App\User ; 

7 

use 

1 1 luminate\Http\Request; 

8 

use 

App\Http\Control lers\Control ler ; 

9 

10 

class  UserController  extends  Controller 

11 

{ 

12 

13 

* Send  an  e-mail  reminder  to  the  user. 

14 

* 

15 

* §param  Request  $request 

16 

* § par am  int  $id 

17 

* §return  Response 

18 

*/ 

19 

public  function  sendEmai lReminder(Request  $request,  $id) 

20 

{ 

21 

$user  ; User :: findOrFai 1 (Sid) ; 

22 

23 

Mai  1 :: send( 1 emai Is . reminder ' , ['user'  =>  Suser] , function  ($m) 

use  ($use\ 

24 

r) 

1 

25 

$m- > from( ' hel lo@app . com ' , 'Your  Application'); 

26 

27 

$m- >to($user- >emai 1 , Suser- >name) - >subject( ' Your  Reminder! 

); 

28 

1); 

29 

1 

30 

1 

Since  we  are  passing  an  array  containing  the  user  key  in  the  example  above,  we 

could  display  the 

user’s  name  within  our  e-mail  view  using  the  following  PHP  code: 

l 

<?php  echo  $user->name;  ?> 

Note:  A $message  variable  is  always  passed  to  e-mail  views,  and  allows  the  inline 
embedding  of  attachments.  So,  you  should  avoid  passing  a message  variable  in  your  view 
payload. 
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Building  The  Message 

As  previously  discussed,  the  third  argument  given  to  the  send  method  is  a Closure  allowing  you 
to  specify  various  options  on  the  e-mail  message  itself.  Using  this  Closure  you  may  specify  other 
attributes  of  the  message,  such  as  carbon  copies,  blind  carbon  copies,  etc: 


1 Mai  1 :: send( ' emai Is . welcome ' , $data,  function  (Smessage)  { 
$message- > from( 1 us@example . com ' , ' Laravel 1 ) ; 

3 

$message- >to( ' foo@example . com ' ) - >cc( 1 bar§example . com ' ) ; 

5 }); 


Here  is  a list  of  the  available  methods  on  the  Smessage  message  builder  instance: 

1 Smessage- > from($address,  Sname  = null); 

2 $message->sender($address,  Sname  = null); 

3 $message->to($address,  Sname  = null); 

4 $message->cc($address,  Sname  = null); 

5 $message->bcc($address,  Sname  = null); 

6 $message->replyTo($address,  Sname  = null); 

7 $message->subject($subject) ; 

8 $message->priority($level ) ; 

9 $message->attach($pathToFile,  array  Soptions  = []); 

10 

11  //  Attach  a file  from  a raw  Sdata  string. . . 

12  $message->attachData($data,  Sname,  array  Soptions  = []); 

13 

14  //  Get  the  underlying  SwiftMailer  message  instance... 

15  $message->getSwi ftMessage( ) ; 


Note:  The  message  instance  passed  to  a Mail:  :send  Closure  extends  the  SwiftMailer 
message  class,  allowing  you  to  call  any  method  on  that  class  to  build  your  e-mail  messages. 


Mailing  Plain  Text 

By  default,  the  view  given  to  the  send  method  is  assumed  to  contain  HTML.  However,  by  passing 
an  array  as  the  first  argument  to  the  send  method,  you  may  specify  a plain  text  view  to  send  in 
addition  to  the  HTML  view: 
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1 Mail :: send( [' html . view ' , ' text . view ' ] , $data,  $callback); 


Or,  if  you  only  need  to  send  a plain  text  e-mail,  you  may  specify  this  using  the  text  key  in  the  array: 


1 Mail : : send  (/"' text ' =>  'view'7,  $data,  $callback); 


Mailing  Raw  Strings 

You  may  use  the  raw  method  if  you  wish  to  e-mail  a raw  string  directly: 

1 Mail : :raw( 'Text  to  e-mail',  function  ($message)  { 

2 // 

3 }); 


Attachments 

To  add  attachments  to  an  e-mail,  use  the  attach  method  on  the  $message  object  passed  to  your 
Closure.  The  attach  method  accepts  the  full  path  to  the  file  as  its  first  argument: 

1 Mail : :send( 'emails. welcome' , $data,  function  (Imessage)  { 

2 // 

3 

4 $message->attach($pathToFile); 

5 }); 


When  attaching  files  to  a message,  you  may  also  specify  the  display  name  and  / or  MIME  type  by 
passing  an  array  as  the  second  argument  to  the  attach  method: 


1 $message->attach($pathToFile,  ['as'  =>  $display,  'mime'  =>  $mime]); 
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Inline  Attachments 

Embedding  An  Image  In  An  E-Mail  View 

Embedding  inline  images  into  your  e-mails  is  typically  cumbersome;  however,  Laravel  provides  a 
convenient  way  to  attach  images  to  your  e-mails  and  retrieving  the  appropriate  CID.  To  embed  an 
inline  image,  use  the  embed  method  on  the  $message  variable  within  your  e-mail  view.  Remember, 
Laravel  automatically  makes  the  $message  variable  available  to  all  of  your  e-mail  views: 


1 

<body> 

2 

Here 

is  an  image: 

3 

4 

<img 

src ="<?php  echo  $message->embed($pathToFile);  ?>"> 

5 

</body> 

Embedding  Raw  Data  In  An  E-Mail  View 


If  you  already  have  a raw  data  string  you  wish  to  embed  into  an  e-mail  message,  you  may  use  the 
embedData  method  on  the  $message  variable: 


1 

<body> 

2 

Here 

is  an  image  from  raw  data: 

3 

4 

<img 

src ="<?php  echo  $message->embedData($data,  $name), 

?>  " > 

5 

</body> 

Queueing  Mail 

Queueing  A Mail  Message 

Since  sending  e-mail  messages  can  drastically  lengthen  the  response  time  of  your  application,  many 
developers  choose  to  queue  e-mail  messages  for  background  sending.  Laravel  makes  this  easy  using 
its  built-in  unified  queue  API.  To  queue  a mail  message,  use  the  queue  method  on  the  Mail  facade: 
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1 Mai  1 :: queue( ' emai Is . welcome ' , $data,  function  ($message)  { 

2 // 

3 }); 


This  method  will  automatically  take  care  of  pushing  a job  onto  the  queue  to  send  the  mail  message 
in  the  background.  Of  course,  you  will  need  to  configure  your  queues  before  using  this  feature. 

Delayed  Message  Queueing 

If  you  wish  to  delay  the  delivery  of  a queued  e-mail  message,  you  may  use  the  later  method.  To  get 
started,  simply  pass  the  number  of  seconds  by  which  you  wish  to  delay  the  sending  of  the  message 
as  the  first  argument  to  the  method: 


1 Mai  1 : : later(5,  ' emai Is . welcome  1 , $data,  function  ($message)  { 

2 // 

3 }); 


Pushing  To  Specific  Queues 

If  you  wish  to  specify  a specific  queue  on  which  to  push  the  message,  you  may  do  so  using  the 
queueOn  and  laterOn  methods: 

1 Mail : :queueOn( 'queue-name' , 1 emai Is . welcome ' , $data,  function  (Smessage)  { 

2 // 

3 }); 

4 

5 Mail :: laterOn( 'queue-name' , 5,  ' emai Is . welcome ' , $data,  function  ($message)  { 

6 // 

7 }); 


Mail  & Local  Development 

When  developing  an  application  that  sends  e-mail,  you  probably  don’t  want  to  actually  send  e-mails 
to  live  e-mail  addresses.  Laravel  provides  several  ways  to  “disable”  the  actual  sending  of  e-mail 
messages. 
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Log  Driver 

One  solution  is  to  use  the  log  mail  driver  during  local  development.  This  driver  will  write  all  e-mail 
messages  to  your  log  files  for  inspection.  For  more  information  on  configuring  your  application  per 
environment,  check  out  the  configuration  documentation. 

Universal  To 

Another  solution  provided  by  Laravel  is  to  set  a universal  recipient  of  all  e-mails  sent  by  the 
framework.  This  way,  all  the  emails  generated  by  your  application  will  be  sent  to  a specific  address, 
instead  of  the  address  actually  specified  when  sending  the  message.  This  can  be  done  via  the  to 
option  in  your  conf  ig/mai  1 . php  configuration  file: 


1  'to'  =>  [ 

'address'  =>  'dev@domain.com', 
'name'  =>  'Dev  Example' 

4 ], 


Mailtrap 

Finally,  you  may  use  a service  like  Mailtrap166  and  the  smtp  driver  to  send  your  e-mail  messages  to  a 
"dummy”  mailbox  where  you  may  view  them  in  a true  e-mail  client.  This  approach  has  the  benefit 
of  allowing  you  to  actually  inspect  the  final  e-mails  in  Mailtrap’ s message  viewer. 

Events 

Laravel  fires  an  event  just  before  sending  mail  messages.  Remember,  this  event  is  fired  when  the  mail 
is  sent,  not  when  it  is  queued.  You  may  register  an  event  listener  in  your  EventServiceProvider: 

1 /** 

2 * The  event  listener  mappings  for  the  application. 

3 * 

4 * §var  array 

5 V 

6 protected  Slisten  = [ 

7 ' II luminate\Mai 1 \Events\MessageSending ' =>  [ 

8 ' App\Listeners\LogSentMessage ' , 

9 ], 


166 


’https://mailtrap.io 
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10  ]; 


Package  Development 

• Introduction 

• Service  Providers 

• Routing 

• Resources  A>  - Views  A>  - Translations  A>  - Configuration 

• Public  Assets 

• Publishing  File  Groups 


Introduction 

Packages  are  the  primary  way  of  adding  functionality  to  Laravel.  Packages  might  be  anything  from 
a great  way  to  work  with  dates  like  Carbon167,  or  an  entire  BDD  testing  framework  like  Behat168. 

Of  course,  there  are  different  types  of  packages.  Some  packages  are  stand-alone,  meaning  they  work 
with  any  framework,  not  just  Laravel.  Both  Carbon  and  Behat  are  examples  of  stand-alone  packages. 
Any  of  these  packages  may  be  used  with  Laravel  by  simply  requesting  them  in  your  composer . json 
file. 

On  the  other  hand,  other  packages  are  specifically  intended  for  use  with  Laravel.  These  packages 
may  have  routes,  controllers,  views,  and  configuration  specifically  intended  to  enhance  a Laravel 
application.  This  guide  primarily  covers  the  development  of  those  packages  that  are  Laravel  specific. 


Service  Providers 

Service  providers  are  the  connection  points  between  your  package  and  Laravel.  A service  provider 
is  responsible  for  binding  things  into  Laravel’s  service  container  and  informing  Laravel  where  to 
load  package  resources  such  as  views,  configuration,  and  localization  files. 

A service  provider  extends  the  1 1 luminate\Support\ServiceProvider  class  and  contains  two 
methods:  register  and  boot.  The  base  ServiceProvider  class  is  located  in  the  i 1 luminate/support 
Composer  package,  which  you  should  add  to  your  own  package’s  dependencies. 

To  learn  more  about  the  structure  and  purpose  of  service  providers,  check  out  their  documentation. 

167https://github.com/briannesbitt/Carbon 
1 6 8https  ://github . com/Behat/Behat 
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Routing 


To  define  routes  for  your  package,  simply  require  the  routes  file  from  within  your  package  service 
provider’s  boot  method.  From  within  your  routes  file,  you  may  use  the  Route  facade  to  register 
routes  just  as  you  would  within  a typical  Laravel  application: 


1 

2 

* Perform  post-registration  booting  of  services . 

3 

* 

4 

* §return  void 

5 

V 

6 

publ ic 

function  boot() 

7 

{ 

8 

if 

(!  $this- >app- >routesAreCached( ) ) { 

9 

require  DIR . ' / ■ ■ / ■ ■ /routes . php 1 2 3 4 5 6 7 ; 

10 

1 

11 

} 

Resources 

Views 

To  register  your  package’s  views  with  Laravel,  you  need  to  tell  Laravel  where  the  views  are  located. 
You  may  do  this  using  the  service  provider’s  loadViewsFrom  method.  The  loadViewsFrom  method 
accepts  two  arguments:  the  path  to  your  view  templates  and  your  package’s  name.  For  example,  if 
your  package  name  is  “courier”,  add  the  following  to  your  service  provider’s  boot  method: 

1 /** 

2 * Perform  post-registration  booting  of  services . 

3 * 

4 * §return  void 

5 V 

6 public  function  boot() 

7 { 

$this- > loadViewsFrom( DIR . ' /path/to/views ' , 1 courier ' ) ; 

9 } 


Package  Development 


380 


Package  views  are  referenced  using  a double-colon  package:  :view  syntax.  So,  you  may  load  the 
admin  view  from  the  courier  package  like  so: 


1 Route :: get( ' admin ' , function  ()  { 


3 }); 


Overriding  Package  Views 

When  you  use  the  loadViewsFrom  method,  Laravel  actually  registers  two  locations  for  your  views: 
one  in  the  application’s  resources/views/vendor  directory  and  one  in  the  directory  you  specify. 

So,  using  our  courier  example:  when  requesting  a package  view,  Laravel  will  first  check  if  a custom 
version  of  the  view  has  been  provided  by  the  developer  in  resources/views/vendor/courier.  Then, 
if  the  view  has  not  been  customized,  Laravel  will  search  the  package  view  directory  you  specified  in 
your  call  to  loadViewsFrom.  This  makes  it  easy  for  end-users  to  customize  / override  your  package’s 
views. 

Publishing  Views 

If  you  would  like  to  make  your  views  available  for  publishing  to  the  application’s  resour  ces/v  i ews/ven  - 
dor  directory,  you  may  use  the  service  provider’s  publishes  method.  The  publishes  method  accepts 
an  array  of  package  view  paths  and  their  corresponding  publish  locations. 


1 /** 

2 * Perform  post-registration  booting  of  services . 

3 * 

4 * § return  void 

5 */ 

6 public  function  boot() 

7 { 

$this- > loadViewsFrom! DIR . ' /path/to/views ' , 1 courier ' ) ; 


2 


return  view( ' courier :: admin ') ; 


9 

10 

11 

12 

13 


$this- >publ ishes( [ 

DIR . ' /path/to/views  1 =>  resource_path( ' views/vendor/cour ier ' ) , 


1); 


Now,  when  users  of  your  package  execute  Laravel’s  vendor : publ  ish  Artisan  command,  your 
package’s  views  will  be  copied  to  the  specified  location. 
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Translations 

If  your  package  contains  translation  files,  you  may  use  the  loadTranslationsFrom  method  to  inform 
Laravel  how  to  load  them.  For  example,  if  your  package  is  named  “courier”,  you  should  add  the 
following  to  your  service  provider’s  boot  method: 


1 /** 

2 * Perform  post-registration  booting  of  services . 

3 * 

4 * §return  void 

5 */ 

6 public  function  boot() 

7 { 

$this- > loadTranslationsFrom( DIR ' /path/to/translations  1 , ' courier ' ) ; 

9 } 


Package  translations  are  referenced  using  a double-colon  package : : f i le . 1 ine  syntax.  So,  you  may 
load  the  courier  package’s  welcome  line  from  the  messages  file  like  so: 


1  echo  trans( ' courier :: messages . welcome ') ; 


Publishing  Translations 

If  you  would  like  to  publish  your  package’s  translations  to  the  application’s  resources/ lang/vendor 
directory,  you  may  use  the  service  provider’s  publishes  method.  The  publishes  method  accepts  an 
array  of  package  paths  and  their  corresponding  publish  locations.  For  example,  to  the  publish  the 
translation  files  for  our  example  courier  package: 

1 /** 

2 * Perform  post-registration  booting  of  services . 

3 * 

4 * §return  void 

5 V 

6 public  function  boot() 

7 { 

$this  - > loadTranslationsFrom( DIR . ' /path/to/translations  1 , ' courier  ' ) ; 

9 

10  $this->publishes( [ 
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DIR . ' /path/to/translations ' =>  resource_path( ' lang/vendor/courier ' ) , 

12  ]); 

13  } 


Now,  when  users  of  your  package  execute  Laravel’s  vendor : publ  ish  Artisan  command,  your 
package’s  translations  will  be  published  to  the  specified  location. 

Configuration 

Typically,  you  will  want  to  publish  your  package’s  configuration  fde  to  the  application’s  own  conf  ig 
directory  This  will  allow  users  of  your  package  to  easily  override  your  default  configuration  options. 
To  publish  a configuration  file,  just  use  the  publishes  method  from  the  boot  method  of  your  service 
provider: 


1 /** 

2 * Perform  post-registration  booting  of  services . 

3 * 

4 * §return  void 

5 V 

6 public  function  boot() 

7 { 

$this- >publ ishes( [ 

DIR . ' /path/to/con fig/courier . php ' =>  conf ig_path( ' courier . php 1 ) , 

10  ]); 

11  } 


Now,  when  users  of  your  package  execute  Laravel’s  vendor:  publ  ish  command,  your  file  will  be 
copied  to  the  specified  location.  Of  course,  once  your  configuration  has  been  published,  it  can  be 
accessed  like  any  other  configuration  file: 

1 lvalue  = conf ig( ' courier . option ') ; 


Default  Package  Configuration 

You  may  also  choose  to  merge  your  own  package  configuration  file  with  the  application’s  copy.  This 
allows  your  users  to  include  only  the  options  they  actually  want  to  override  in  the  published  copy 
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of  the  configuration.  To  merge  the  configurations,  use  the  mergeConf  igFrom  method  within  your 
service  provider’s  register  method: 


1 

2 

* Register  bindings  in  the  container . 

3 

* 

4 

* §return  void 

5 

V 

6 

public  function  register () 

7 

{ 

8 

$this- > mergeConf igFrom( 

9 

DIR . ' /path/to/conf ig/cour ier . php ' , 

' courier ' 

10 

); 

11 

1 

Public  Assets 

Your  packages  may  have  assets  such  as  JavaScript,  CSS,  and  images.  To  publish  these  assets  to  the 
application’s  public  directory,  use  the  service  provider’s  publishes  method.  In  this  example,  we 
will  also  add  a public  asset  group  tag,  which  may  be  used  to  publish  groups  of  related  assets: 


1 /** 

2 * Perform  post -registration  booting  of  services . 

3 * 

4 * §return  void 

5 V 

6 public  function  boot() 

7 { 

$this- >publ ishes( [ 

DIR .'/path/to/assets'  =>  publ ic_path( ' vendor/courier ') , 

10  ] , ' public  1 2 3 4 5 6 7 * * 10 11 ) ; 

11  } 


Now,  when  your  package’s  users  execute  the  vendor : publish  command,  your  assets  will  be  copied 
to  the  specified  location.  Since  you  typically  will  need  to  overwrite  the  assets  every  time  the  package 
is  updated,  you  may  use  the  - - force  flag: 
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1 php  artisan  vendor : publ ish  --tag=public  --force 


If  you  would  like  to  make  sure  your  public  assets  are  always  up-to-date,  you  can  add  this  command 
to  the  post-update-cmd  list  in  your  composer . json  file. 

Publishing  File  Groups 

You  may  want  to  publish  groups  of  package  assets  and  resources  separately.  For  instance,  you  might 
want  your  users  to  be  able  to  publish  your  package’s  configuration  files  without  being  forced  to 
publish  your  package’s  assets  at  the  same  time.  You  may  do  this  by  “tagging”  them  when  calling  the 
publishes  method.  For  example,  let’s  define  two  publish  groups  in  the  boot  method  of  a package 
service  provider: 


1 /** 

2 * Perform  post -registration  booting  of  services . 

3 * 

4 * §return  void 

5 V 

6 public  function  boot() 

7 { 

$this- >publ ishes( [ 

DIR . ' / ■ ■ /conf ig/package . php ' =>  config_path( ’ package . php ' ) 

10  ],  ’config’); 

11 

12  $this- >publ ishes(  [ 

13  DIR . ' / . . /database/migrations/ ' =>  database_path( ' migrations ' ) 

14  ] , ' migrations ' ) ; 

15  } 


Now  your  users  may  publish  these  groups  separately  by  referencing  their  tag  name  when  using  the 
vendor : publish  Artisan  command: 

1 php  artisan  vendor : publ ish  - -provider="Vendor\Providers\PackageServiceProvider " \ 

2 - -tag="conf ig" 


Pagination 

• Introduction 

• Basic  Usage  A>  - Paginating  Query  Builder  Results  A>  - Paginating  Eloquent  Results  A>  - 
Manually  Creating  A Paginator 

• Displaying  Results  In  A View 

• Converting  Results  To  JSON 


Introduction 

In  other  frameworks,  pagination  can  be  very  painful.  Laravel  makes  it  a breeze.  Laravel  can  quickly 
generate  an  intelligent  “range”  of  links  based  on  the  current  page,  and  the  generated  HTML  is 
compatible  with  the  Bootstrap  CSS  framework169. 

Basic  Usage 

Paginating  Query  Builder  Results 

There  are  several  ways  to  paginate  items.  The  simplest  is  by  using  the  paginate  method  on  the  query 
builder  or  an  Eloquent  query.  The  paginate  method  provided  by  Laravel  automatically  takes  care 
of  setting  the  proper  limit  and  offset  based  on  the  current  page  being  viewed  by  the  user.  By  default, 
the  current  page  is  detected  by  the  value  of  the  ?page  query  string  argument  on  the  HTTP  request. 
Of  course,  this  value  is  automatically  detected  by  Laravel,  and  is  also  automatically  inserted  into 
links  generated  by  the  paginator. 

Lirst,  let’s  take  a look  at  calling  the  paginate  method  on  a query.  In  this  example,  the  only  argument 
passed  to  paginate  is  the  number  of  items  you  would  like  displayed  “per  page”.  In  this  case,  let’s 
specify  that  we  would  like  to  display  15  items  per  page: 


169http://getbootstrap.com/ 
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1 < ?php 

2 

3 namespace  App\Http\Control lers; 

4 

5 use  DB; 

6 use  App\Http\Controllers\Controller; 

7 

8 class  UserController  extends  Controller 

9 { 

10  /** 

11  * Show  all  of  the  users  for  the  application. 

12  * 

13  * §return  Response 

14  */ 

15  public  function  index() 

16  { 

17  $users  = DB  : table( ' users ')- >paginate(15) ; 

18 

return  view( 1 user . index ' , ['users'  =>  $users]); 

20  } 

21  } 


Note:  Currently,  pagination  operations  that  use  a groupBy  statement  cannot  be  executed 
efficiently  by  Laravel.  If  you  need  to  use  a groupBy  with  a paginated  result  set,  it  is 
recommended  that  you  query  the  database  and  create  a paginator  manually. 


"Simple  Pagination" 


If  you  only  need  to  display  simple  “Next”  and  “Previous”  links  in  your  pagination  view,  you  have  the 
option  of  using  the  simplePaginate  method  to  perform  a more  efficient  query.  This  is  very  useful 
for  large  datasets  if  you  do  not  need  to  display  a link  for  each  page  number  when  rendering  your 
view: 

1 $users  = DB :: table( ' users ')- >simplePaginate(15) ; 
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Paginating  Eloquent  Results 


You  may  also  paginate  Eloquent  queries.  In  this  example,  we  will  paginate  the  User  model  with  15 
items  per  page.  As  you  can  see,  the  syntax  is  nearly  identical  to  paginating  query  builder  results: 


1 

Susers  = App\User : : paginate(15) ; 

Of  course,  you  may  call  paginate  after  setting  other  constraints  on  the  query,  such  as  where  clauses: 

l 

Susers  = User :: where (' votes ' , 100) ->paginate(15) ; 

You 

may  also  use  the  simp  lePaginate  method  when  paginating  Eloquent  models: 

l 

Susers  = User :: where( ' votes ' , 100) ->simplePaginate(15) ; 

Manually  Creating  A Paginator 

Sometimes  you  may  wish  to  create  a pagination  instance  manually,  passing  it  an  array  of  items.  You 

may  do  so  by  creating  either  an  1 1 luminate\Pagination\Paginator  or  1 1 luminate\Pagination\LengthAwarePag 

instance,  depending  on  your  needs. 

The  Paginator  class  does  not  need  to  know  the  total  number  of  items  in  the  result  set;  however, 
because  of  this,  the  class  does  not  have  methods  for  retrieving  the  index  of  the  last  page.  The 
LengthAwarePaginator  accepts  almost  the  same  arguments  as  the  Paginator;  however,  it  does 
require  a count  of  the  total  number  of  items  in  the  result  set. 

In  other  words,  the  Paginator  corresponds  to  the  simp lePaginate  method  on  the  query  builder  and 
Eloquent,  while  the  LengthAwarePaginator  corresponds  to  the  paginate  method. 

When  manually  creating  a paginator  instance,  you  should  manually  “slice”  the  array  of  results  you 
pass  to  the  paginator.  If  you’re  unsure  how  to  do  this,  check  out  the  array _slice170  PHP  function. 

Displaying  Results  In  A View 

When  you  call  the  paginate  or  simp  lePaginate  methods  on  a query  builder  or  Eloquent  query,  you 
will  receive  a paginator  instance.  When  calling  the  paginate  method,  you  will  receive  an  instance 

1 7 °http  ://php . net/manual/en/function.  array-  slice,  php 
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of  1 1 luminate\Pagination\LengthAwarePaginator.  When  calling  the  simplePaginate  method, 
you  will  receive  an  instance  of  1 1 luminate\Pagination\Paginator.  These  objects  provide  several 
methods  that  describe  the  result  set.  In  addition  to  these  helpers  methods,  the  paginator  instances 
are  iterators  and  may  be  looped  as  an  array 

So,  once  you  have  retrieved  the  results,  you  may  display  the  results  and  render  the  page  links  using 
Blade: 


1 <div  class="container" > 

@foreach  ($users  as  $user) 
{{  $user->name  }} 

4 §endforeach 

5 </div> 

6 

7 {!!  $users- > 1 inks( ) !!} 


The  links  method  will  render  the  links  to  the  rest  of  the  pages  in  the  result  set.  Each  of  these  links 
will  already  contain  the  proper  ?page  query  string  variable.  Remember,  the  HTML  generated  by  the 
links  method  is  compatible  with  the  Bootstrap  CSS  framework171. 

Customizing  The  Paginator  URI 

The  setPath  method  allows  you  to  customize  the  URI  used  by  the  paginator  when  generating  links. 
For  example,  if  you  want  the  paginator  to  generate  links  like  http : //example . com/custom/ur  1 ?page=N, 
you  should  pass  custom/ur  1 to  the  setPath  method: 


1 Route :: get( ' users ' , function  ()  { 

$users  App\User  . paginate(15) ; 

3 

$users- >setPath( 1 custom/url ' ) ; 

5 

6 // 

7 }); 


Appending  To  Pagination  Links 

You  may  add  to  the  query  string  of  pagination  links  using  the  appends  method.  For  example,  to 
append  &sort=votes  to  each  pagination  link,  you  should  make  the  following  call  to  appends: 

171 


https://getbootstrap.com 
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1 {!!  $users- >appends( [ ' sort ' =>  ' votes '])-> 1 inks( ) !!} 


If  you  wish  to  append  a “hash  fragment”  to  the  paginator’s  URLs,  you  may  use  the  fragment  method. 
For  example,  to  append  #foo  to  the  end  of  each  pagination  link,  make  the  following  call  to  the 
fragment  method: 

1 {!!  $users- > fragment! ' foo ') -> 1 inks( ) !!} 


Additional  Helper  Methods 

You  may  also  access  additional  pagination  information  via  the  following  methods  on  paginator 
instances: 

• $results- >count( ) 

• $results- >currentPage( ) 

• $results- > f irstltem( ) 

• $results- >hasMorePages( ) 

• $results- > lastltem( ) 

• $results- > lastPage( ) (Not  available  when  using  simplePaginate) 

• $results- >nextPageUrl ( ) 

• $results- >perPage( ) 

• $results- >previousPagellr  1 ( ) 

• $results- > total ( ) (Not  available  when  using  simplePaginate) 

• $results->url($page) 


Converting  Results  To  JSON 

TheLaravel  paginator  result  classes  implement  the  1 1 luminate\Contracts\Support\JsonableInterface 
contract  and  expose  the  toJson  method,  so  it’s  very  easy  to  convert  your  pagination  results  to  JSON. 

You  may  also  convert  a paginator  instance  to  JSON  by  simply  returning  it  from  a route  or  controller 
action: 
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1 Route :: get( ' users ' , function  ()  { 
return  App\User  :paginate(); 

3 }); 


The  JSON  from  the  paginator  will  include  meta  information  such  as  total,  current_page,  last_- 
page,  and  more.  The  actual  result  objects  will  be  available  via  the  data  key  in  the  JSON  array.  Here 
is  an  example  of  the  JSON  created  by  returning  a paginator  instance  from  a route: 


Example  Paginator  JSON 


1 

{ 

2 

"total":  50, 

3 

"per_page":  15, 

4 

"current_page" : 1, 

5 

" last_page" : 4, 

6 

"next_page_url " : "http : //laravel . app?page=2" , 

7 

" prev_page_ur 1 " : null, 

8 

"from":  1, 

9 

"to" : 15, 

10 

"data" : [ 

11 

{ 

12 

//  Result  Object 

13 

}, 

14 

{ 

15 

//  Result  Object 

16 

} 

17 

] 

18 

} 
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Introduction 

The  Laravel  queue  service  provides  a unified  API  across  a variety  of  different  queue  back-ends. 
Queues  allow  you  to  defer  the  processing  of  a time  consuming  task,  such  as  sending  an  e-mail,  until 
a later  time  which  drastically  speeds  up  web  requests  to  your  application. 

Configuration 

The  queue  configuration  file  is  stored  in  config/queue.php.  In  this  file  you  will  find  connection 
configurations  for  each  of  the  queue  drivers  that  are  included  with  the  framework,  which  includes 
a database,  Beanstalkd172,  Amazon  SQS173,  Redis174,  and  synchronous  (for  local  use)  driver. 

A nul  1 queue  driver  is  also  included  which  simply  discards  queued  jobs. 

Driver  Prerequisites 

Database 

In  order  to  use  the  database  queue  driver,  you  will  need  a database  table  to  hold  the  jobs.  To  generate 
a migration  that  creates  this  table,  run  the  queue: table  Artisan  command.  Once  the  migration  is 
created,  you  may  migrate  your  database  using  the  migrate  command: 


1 7 2http://kr.github  .com/beanstalkd 

173http://aws.amazon.com/sqs 

174http://redis.io 
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1 php  artisan  queue:table 

2 

3 php  artisan  migrate 


Other  Queue  Dependencies 

The  following  dependencies  are  needed  for  the  listed  queue  drivers: 

• Amazon  SQS:  aws/aws-sdk-php  ~3.0 

• Beanstalkd:  pda/pheanstalk  ~3.0 

• Redis:  predi  s/pred  is  ~1.0 

Writingjob  Classes 

Generatingjob  Classes 

By  default,  all  of  the  queueable  jobs  for  your  application  are  stored  in  the  app/Jobs  directory.  You 
may  generate  a new  queued  job  using  the  Artisan  CLI: 

1 php  artisan  make: job  SendReminderEmai 1 


This  command  will  generate  a new  class  in  the  app/Jobs  directory,  and  the  class  will  implement  the 
1 1 luminate\Contracts\Queue\ShouldQueue  interface,  indicating  to  Laravel  that  the  job  should  be 
pushed  onto  the  queue  instead  of  run  synchronously. 

Job  Class  Structure 

Job  classes  are  very  simple,  normally  containing  only  a handle  method  which  is  called  when  the  job 
is  processed  by  the  queue.  To  get  started,  let’s  take  a look  at  an  example  job  class: 
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1 < ?php 

2 

3 namespace  App\Jobs; 

4 

5 use  App\User; 

6 use  App\Jobs\Job; 

7 use  Illuminate\Contracts\Mail\Mailer; 

8 use  1 1 luminate\Queue\Ser ial izesModels; 

9 use  1 1 luminate\Queue\InteractsWithQueue; 

10  use  1 1 luminate\Contracts\Queue\ShouldQueue; 

11 

12  class  SendReminderEmail  extends  Job  implements  ShouldQueue 

13  { 

14  use  InteractsWithQueue,  Serial izesModels; 

15 

16  protected  $user; 

17 

18  /** 

19  * Create  a new  job  instance. 

20  * 

21  * §param  User  $user 

22  * §return  void 

23  V 

24  public  function  construct(User  $user) 

25  { 

26  $this->user  = $user; 

27  } 

28 

29  /** 

30  * Execute  the  job. 

31  * 

32  * §param  Mailer  $ mailer 

33  * §return  void 

34  V 

35  public  function  handle(Mai ler  $mailer) 

36  { 

$mai ler->send( ' emai Is . reminder ' , ['user'  =>  $this- >user] , function  ($m)  { 

38  // 

39  }); 

40 

41  $this->user->reminders( )->create( . . . ) ; 

42  } 

43  } 
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In  this  example,  note  that  we  were  able  to  pass  an  Eloquent  model  directly  into  the  queued  job’s 
constructor.  Because  of  the  Serial  izesModels  trait  that  the  job  is  using,  Eloquent  models  will  be 
gracefully  serialized  and  unserialized  when  the  job  is  processing.  If  your  queued  job  accepts  an 
Eloquent  model  in  its  constructor,  only  the  identifier  for  the  model  will  be  serialized  onto  the  queue. 
When  the  job  is  actually  handled,  the  queue  system  will  automatically  re-retrieve  the  full  model 
instance  from  the  database.  It’s  all  totally  transparent  to  your  application  and  prevents  issues  that 
can  arise  from  serializing  full  Eloquent  model  instances. 

The  handle  method  is  called  when  the  job  is  processed  by  the  queue.  Note  that  we  are  able  to  type- 
hint  dependencies  on  the  handle  method  of  the  job.  The  Laravel  service  container  automatically 
injects  these  dependencies. 

When  Things  Go  Wrong 

If  an  exception  is  thrown  while  the  job  is  being  processed,  it  will  automatically  be  released  back 
onto  the  queue  so  it  may  be  attempted  again.  The  job  will  continue  to  be  released  until  it  has  been 
attempted  the  maximum  number  of  times  allowed  by  your  application.  The  number  of  maximum 
attempts  is  defined  by  the  - -tries  switch  used  on  the  queue:  listen  or  queue: work  Artisan  jobs. 
More  information  on  running  the  queue  listener  can  be  found  below. 

Manually  Releasing  Jobs 

If  you  would  like  to  release  the  job  manually,  the  InteractsWithQueue  trait,  which  is  already 
included  in  your  generated  job  class,  provides  access  to  the  queue  job  release  method.  The  release 
method  accepts  one  argument:  the  number  of  seconds  you  wish  to  wait  until  the  job  is  made  available 
again: 


1 public  function  handle(Mai ler  $mailer) 

2 { 

if  (condition)  { 

$this- >release(10) ; 

5 } 

6 } 


Checking  The  Number  Of  Run  Attempts 

As  noted  above,  if  an  exception  occurs  while  the  job  is  being  processed,  it  will  automatically  be 
released  back  onto  the  queue.  You  may  check  the  number  of  attempts  that  have  been  made  to  run 
the  job  using  the  attempts  method: 
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1 

publ ic 

function  handle(Mai ler  Smailer) 

2 

{ 

3 

if 

( Sthis- >attempts( ) > 3)  { 

4 

// 

5 

} 

6 

} 

Pushingjobs  Onto  The  Queue 

The  default  Laravel  controller  located  in  app/Http/Control  lers/Control  ler . php  uses  a Dispatch- 
esJobs  trait.  This  trait  provides  several  methods  allowing  you  to  conveniently  push  jobs  onto  the 
queue,  such  as  the  dispatch  method: 

1 < ?php 

2 

3 namespace  App\Http\Control lers; 

4 

5 use  App\User; 

6 use  1 1 luminate\Http\Request; 

7 use  App\Jobs\SendReminderEmai 1 ; 

8 use  App\Http\Controllers\Controller; 

9 

10  class  UserController  extends  Controller 

11  { 

12  /** 

13  * Send  a reminder  e-mail  to  a given  user. 

14  * 

15  * §param  Request  $request 

16  * §param  int  $id 

17  * §return  Response 

18  */ 

19  public  function  sendReminderEmai 1 (Request  $request,  Sid) 

20  { 

21  Suser  = User : : f indOrFai 1 ($id) ; 

22 

Sthis- >dispatch( new  SendReminderEmai 1 (Suser ) ) ; 

24  } 

25  } 
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The  DispatchesJobs  Trsit 

Of  course,  sometimes  you  may  wish  to  dispatch  a job  from  somewhere  in  your  application  besides  a 
route  or  controller.  For  that  reason,  you  can  include  the  DispatchesJobs  trait  on  any  of  the  classes 
in  your  application  to  gain  access  to  its  various  dispatch  methods.  For  example,  here  is  a sample 
class  that  uses  the  trait: 


1 < ?php 

2 

3 namespace  App; 

4 

5 use  Illuminate\Foundation\Bus\DispatchesJobs; 

6 

7 class  ExampleClass 

8 { 

9 use  DispatchesJobs; 

10  } 


The  dispatch  Function 

Or,  you  may  use  the  dispatch  global  function: 


1 Route :: get( ' /job ' , function  ()  { 

dispatch(new  App\Jobs\PerformTask) ; 

3 

4 return  ' Done ! ' ; 

5 }); 


Specifying  The  Queue  For  AJob 

You  may  also  specify  the  queue  a job  should  be  sent  to. 

By  pushing  jobs  to  different  queues,  you  may  “categorize”  your  queued  jobs,  and  even  prioritize  how 
many  workers  you  assign  to  various  queues.  This  does  not  push  jobs  to  different  queue  “connections” 
as  defined  by  your  queue  configuration  file,  but  only  to  specific  queues  within  a single  connection. 
To  specify  the  queue,  use  the  onQueue  method  on  the  job  instance.  The  onQueue  method  is  provided 
by  the  Illuminate\Bus\Queueable  trait,  which  is  already  included  on  the  App\Jobs\Job  base  class: 
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1 

<?php 

2 

3 

namespace  App\Http\Control lers; 

4 

5 

use  App\User; 

6 

use  1 1 luminate\Http\Request; 

7 

use  App\Jobs\SendReminderEmai 1 ; 

8 

use  App\Http\Control lers\Control ler ; 

9 

10 

class  UserController  extends  Controller 

11 

{ 

12 

/** 

13 

* Send  a reminder  e-mail  to  a given  user. 

14 

* 

15 

* §param  Request  $request 

16 

* § par am  int  $id 

17 

* §return  Response 

18 

*/ 

19 

public  function  sendReminderEmail(Request  $request, 

Sid) 

20 

{ 

21 

$user  = User :: findOrFai 1 (Sid) ; 

22 

23 

Sjob  = (new  SendReminderEmail($user))->onQueue( 

emai Is  1 ) ; 

24 

25 

Sthis- >dispatch($job) ; 

26 

1 

27 

} 

Delayed  Jobs 

Sometimes  you  may  wish  to  delay  the  execution  of  a queued  job.  For  instance,  you  may  wish  to 
queue  a job  that  sends  a customer  a reminder  e-mail  5 minutes  after  sign-up.  You  may  accomplish 
this  using  the  delay  method  on  your  job  class,  which  is  provided  by  the  Illuminate\Bus  \Queueab  1 e 
trait: 
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1 < ?php 

2 

3 namespace  App\Http\Control lers; 

4 

5 use  App\User; 

6 use  1 1 luminate\Http\Request; 

7 use  App\Jobs\SendReminderEmai 1 ; 

8 use  App\Http\Controllers\Controller; 

9 

10  class  UserController  extends  Controller 

11  { 

12  /** 

13  * Send  a reminder  e-mail  to  a given  user. 

14  * 

15  * §param  Request  $request 

16  * §param  int  $id 

17  * §return  Response 

18  */ 

19  public  function  sendReminderEmai 1 (Request  $request,  $id) 

20  { 

21  $user  User  : f indOrFai 1 ($id) ; 

22 

$job  = (new  SendReminderEmail($user))->delay(60  * 5); 

24 

25  $this->dispatch($job) ; 

26  } 

27  } 


In  this  example,  we’re  specifying  that  the  job  should  be  delayed  in  the  queue  for  5 minutes  before 
being  made  available  to  workers. 


Note:  The  Amazon  SQS  service  has  a maximum  delay  time  of  15  minutes. 


Job  Events 

Job  Completion  Event 

The  Queue:  : after  method  allows  you  to  register  a callback  to  be  executed  when  a queued  job 
executes  successfully.  This  callback  is  a great  opportunity  to  perform  additional  logging,  queue  a 
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subsequent  job,  or  increment  statistics  for  a dashboard.  For  example,  we  may  attach  a callback  to 
this  event  from  the  AppServiceProvider  that  is  included  with  Laraveb 


1 < ?php 

2 

3 namespace  App\Providers; 

4 

5 use  Queue; 

6 use  1 1 luminate\Support\ServiceProvider ; 

7 use  Illuminate\Queue\Events\JobProcessed; 

8 

9 class  AppServiceProvider  extends  ServiceProvider 

10  { 

11  /** 

12  * Bootstrap  any  application  services. 

13  * 

14  * § return  void 

15  */ 

16  public  function  boot() 

17  { 

Queue :: after ( function  ( JobProcessed  $event)  { 

19  //  $event->connection 

20  //  $event->job 

21  //  $event->data 

22  }); 

23  } 

24 

25  /** 

26  * Register  the  service  provider. 

27  * 

28  * §return  void 

29  */ 

30  public  function  registerQ 

31  { 

32  // 

33  } 

34 


1 
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Running  The  Queue  Listener 

Starting  The  Queue  Listener 

Laravel  includes  an  Artisan  command  that  will  run  new  jobs  as  they  are  pushed  onto  the  queue. 
You  may  run  the  listener  using  the  queue : listen  command: 

1 php  artisan  queue: listen 


You  may  also  specify  which  queue  connection  the  listener  should  utilize: 
1 php  artisan  queue: listen  connection 


Note  that  once  this  task  has  started,  it  will  continue  to  run  until  it  is  manually  stopped.  You  may  use 
a process  monitor  such  as  Supervisor175  to  ensure  that  the  queue  listener  does  not  stop  running. 

Queue  Priorities 

You  may  pass  a comma-delimited  list  of  queue  connections  to  the  listen  job  to  set  queue  priorities: 
1 php  artisan  queue: listen  - -queue=high, low 


In  this  example,  jobs  on  the  high  queue  will  always  be  processed  before  moving  onto  jobs  from  the 
low  queue. 


Specifying  The  Job  Timeout  Parameter 

You  may  also  set  the  length  of  time  (in  seconds)  each  job  should  be  allowed  to  run: 
1 php  artisan  queue: listen  --timeout=60 


175 


’http://supervisord.org/ 
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Specifying  Queue  Sleep  Duration 

In  addition,  you  may  specify  the  number  of  seconds  to  wait  before  polling  for  new  jobs: 

1 php  artisan  queue: listen  --sleep=5 


Note  that  the  queue  only  “sleeps”  if  no  jobs  are  on  the  queue.  If  more  jobs  are  available,  the  queue 
will  continue  to  work  them  without  sleeping. 

Supervisor  Configuration 

Supervisor  is  a process  monitor  for  the  Linux  operating  system,  and  will  automatically  restart  your 
queue : listen  or  queue : work  commands  if  they  fail.  To  install  Supervisor  on  Ubuntu,  you  may  use 
the  following  command: 


1  sudo  apt-get  install  supervisor 


Supervisor  configuration  files  are  typically  stored  in  the  /etc/supervisor/con f . d directory.  Within 
this  directory,  you  may  create  any  number  of  configuration  files  that  instruct  supervisor  how  your 
processes  should  be  monitored.  For  example,  let’s  create  a laravel  - worker . conf  file  that  starts  and 
monitors  a queue : work  process: 


1 [program : laravel -worker] 

2 process_name=%(program_name)s_%(process_num)02d 

3 command=php  /home/ forge/app . com/artisan  queue: work  sqs  --sleep=3  --tries=3  --dae\ 

4 mon 

5 autostart=true 

6 autorestart=true 

7 user = forge 

8 numprocs=8 

9 redirect_stderr=true 

10  stdout_logf i le=/home/forge/app . com/worker . log 


In  this  example,  the  numprocs  directive  will  instruct  Supervisor  to  run  8 queue: work  processes  and 
monitor  all  of  them,  automatically  restarting  them  if  they  fail.  Of  course,  you  should  change  the 
queue : work  sqs  portion  of  the  command  directive  to  reflect  your  chosen  queue  driver. 
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Once  the  configuration  file  has  been  created,  you  may  update  the  Supervisor  configuration  and  start 
the  processes  using  the  following  commands: 


1 sudo  supervisorctl  reread 

2 

3 sudo  supervisorctl  update 

4 

5 sudo  supervisorctl  start  laravel -worker : * 


For  more  information  on  configuring  and  using  Supervisor,  consult  the  Supervisor  documentation176. 
Alternatively,  you  may  use  Laravel  Forge177  to  automatically  configure  and  manage  your  Supervisor 
configuration  from  a convenient  web  interface. 

Daemon  Queue  Listener 

The  queue: work  Artisan  command  includes  a --daemon  option  for  forcing  the  queue  worker  to 
continue  processing  jobs  without  ever  re-booting  the  framework.  This  results  in  a significant 
reduction  of  CPU  usage  when  compared  to  the  queue : listen  command: 

To  start  a queue  worker  in  daemon  mode,  use  the  - - daemon  flag: 

1 php  artisan  queue: work  connection  --daemon 

2 

3 php  artisan  queue: work  connection  --daemon  --sleep=3 

4 

5 php  artisan  queue: work  connection  --daemon  --sleep=3  --tries=3 


As  you  can  see,  the  queue:  work  job  supports  most  of  the  same  options  available  to  queue:  listen. 
You  may  use  the  php  artisan  help  queue : work  job  to  view  all  of  the  available  options. 

Coding  Considerations  For  Daemon  Queue  Listeners 

Daemon  queue  workers  do  not  restart  the  framework  before  processing  each  job.  Therefore,  you 
should  be  careful  to  free  any  heavy  resources  before  your  job  finishes.  For  example,  if  you  are  doing 
image  manipulation  with  the  GD  library,  you  should  free  the  memory  with  imagedestroy  when  you 
are  done. 

Similarly,  your  database  connection  may  disconnect  when  being  used  by  a long-running  daemon. 
You  may  use  the  DB : : reconnect  method  to  ensure  you  have  a fresh  connection. 

176http://supervisord.org/index.html 

177https://forge.laravel.com 
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Deploying  With  Daemon  Queue  Listeners 

Since  daemon  queue  workers  are  long-lived  processes,  they  will  not  pick  up  changes  in  your  code 
without  being  restarted.  So,  the  simplest  way  to  deploy  an  application  using  daemon  queue  workers 
is  to  restart  the  workers  during  your  deployment  script.  You  may  gracefully  restart  all  of  the  workers 
by  including  the  following  command  in  your  deployment  script: 


1 php  artisan  queue : restart 


This  command  will  gracefully  instruct  all  queue  workers  to  restart  after  they  finish  processing  their 
current  job  so  that  no  existing  jobs  are  lost. 


Note:  This  command  relies  on  the  cache  system  to  schedule  the  restart.  By  default,  APCu 
does  not  work  for  CLI  jobs.  If  you  are  using  APCu,  add  ape . enable_cl  i=l  to  your  APCu 
configuration. 


Dealing  With  Failed  Jobs 

Since  things  don’t  always  go  as  planned,  sometimes  your  queued  jobs  will  fail.  Don’t  worry,  it 
happens  to  the  best  of  us!  Laravel  includes  a convenient  way  to  specify  the  maximum  number 
of  times  a job  should  be  attempted.  After  a job  has  exceeded  this  amount  of  attempts,  it  will  be 
inserted  into  a fai  led_jobs  table.  The  name  of  the  table  can  be  configured  via  the  con  fig/queue . php 
configuration  file. 

To  create  a migration  for  the  failed_jobs  table,  you  may  use  the  queue:  failed-table  command: 


1 php  artisan  queue : fai led-table 


When  running  your  queue  listener,  you  may  specify  the  maximum  number  of  times  a job  should  be 
attempted  using  the  - - tries  switch  on  the  queue : listen  command: 

1 php  artisan  queue: listen  connection-name  --tries=3 
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Failed  Job  Events 

If  you  would  like  to  register  an  event  that  will  be  called  when  a queued  job  fails,  you  may  use 
the  Queue:  : failing  method.  This  event  is  a great  opportunity  to  notify  your  team  via  e-mail  or 
HipChat178.  For  example,  we  may  attach  a callback  to  this  event  from  the  AppServiceProvider  that 
is  included  with  Laravel: 


1 < ?php 

2 

3 namespace  App\Providers; 

4 

5 use  Queue; 

6 use  1 1 luminate\Queue\Events\JobFai led; 

7 use  1 1 luminate\Support\ServiceProvider ; 

8 

9 class  AppServiceProvider  extends  ServiceProvider 

10  { 

11  /** 

12  * Bootstrap  any  application  services. 

13  * 

14  * §return  void 

15  */ 

16  public  function  boot() 

17  { 

Queue :: fai 1 ing( function  (JobFailed  $event)  { 

19  //  $event->connection 

20  //  $event->$job 

21  //  $event->$data 

22  }); 

23  } 

24 

25  /** 

26  * Register  the  service  provider. 

27  * 

28  * §return  void 

29  */ 

30  public  function  registerQ 

31  { 

32  // 

33  } 

34  } 


littps:/ Avww.hipchat.com 
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Failed  Method  On  Job  Classes 

For  more  granular  control,  you  may  define  a failed  method  directly  on  a queue  job  class,  allowing 
you  to  perform  job  specific  actions  when  a failure  occurs: 


1 < ?php 

2 

3 namespace  App\Jobs; 

4 

5 use  App\Jobs\Job; 

6 use  1 1 luminate\Contracts\Mai l\Mai ler ; 

7 use  Illuminate\Queue\SerializesModels; 

8 use  1 1 luminate\Queue\InteractsWithQueue; 

9 use  1 1 luminate\Contracts\Queue\ShouldQueue; 

10 

11  class  SendReminderEmail  extends  Job  implements  ShouldQueue 

12  { 

13  use  InteractsWithQueue,  Serial izesModels; 

14 

15  /** 

16  * Execute  the  job. 

17  * 

18  * § pa ram  Mailer  Smaller 

19  * §return  void 

20  */ 

21  public  function  handle(Mai ler  $mailer) 

22  { 

23  // 

24  } 

25 

26  /** 

27  * Handle  a job  failure. 

28  * 

29  * §return  void 

30  */ 

31  public  function  failed() 

32  { 

33  //  Called  when  the  job  is  failing. . . 

34  } 

35 


} 
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Retrying  Failed  Jobs 

To  view  all  of  your  failed  jobs  that  have  been  inserted  into  your  failed_jobs  database  table,  you 
may  use  the  queue : fai  led  Artisan  command: 

1 php  artisan  queue: failed 


The  queue : fai  led  command  will  list  the  job  ID,  connection,  queue,  and  failure  time.  The  job  ID  may 
be  used  to  retry  the  failed  job.  For  instance,  to  retry  a failed  job  that  has  an  ID  of  5,  the  following 
command  should  be  issued: 

1 php  artisan  queue: retry  5 


To  retry  all  of  your  failed  jobs,  use  queue : retry  with  al  1 as  the  ID: 
1 php  artisan  queue: retry  all 


If  you  would  like  to  delete  a failed  job,  you  may  use  the  queue : forget  command: 
1 php  artisan  queue: forget  5 


To  delete  all  of  your  failed  jobs,  you  may  use  the  queue : flush  command: 
1 php  artisan  queue: flush 
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Introduction 

Redis179  is  an  open  source,  advanced  key-value  store.  It  is  often  referred  to  as  a data  structure  server 
since  keys  can  contain  strings180,  hashes181,  lists182,  sets183,  and  sorted  sets184.  Before  using  Redis  with 
Laravel,  you  will  need  to  install  the  predis/predis  package  (~1.0)  via  Composer. 

Configuration 

The  Redis  configuration  for  your  application  is  located  in  the  config/database.php  configuration 
file.  Within  this  file,  you  will  see  a red  i s array  containing  the  Redis  servers  used  by  your  application: 


1 'redis'  =>  [ 

2 

'cluster'  =>  false, 

4 

'default'  =>  [ 

'host'  =>  '127.0.0.1 ' , 
'port'  =>  6379, 
’database'  =>  0, 

9 ], 

10 

11  ], 


179http://redis.io 

180http://redis.io/topics/data-types#strings 
181http://redis.io/topics/data-types#hashes 
1 8 2http  ://redis  .io/topics/  data-  types#lists 
183http://redis.io/topics/data-types#sets 
1 84http:// redis.io/topics/  data-  types#sorted-  sets 
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The  default  server  configuration  should  suffice  for  development.  However,  you  are  free  to  modify 
this  array  based  on  your  environment.  Simply  give  each  Redis  server  a name,  and  specify  the  host 
and  port  used  by  the  server. 

The  cluster  option  will  tell  the  Laravel  Redis  client  to  perform  client-side  sharding  across  your 
Redis  nodes,  allowing  you  to  pool  nodes  and  create  a large  amount  of  available  RAM.  However, 
note  that  client-side  sharding  does  not  handle  failover;  therefore,  is  primarily  suited  for  cached  data 
that  is  available  from  another  primary  data  store. 

Additionally,  you  may  define  an  options  array  value  in  your  Redis  connection  definition,  allowing 
you  to  specify  a set  of  Predis  client  options185. 

If  your  Redis  server  requires  authentication,  you  may  supply  a password  by  adding  a password 
configuration  item  to  your  Redis  server  configuration  array. 


Note:  If  you  have  the  Redis  PHP  extension  installed  via  PECL,  you  will  need  to  rename 
the  alias  for  Redis  in  your  config/app.php  file. 


Basic  Usage 

You  may  interact  with  Redis  by  calling  various  methods  on  the  Redis  facade.  The  Redis  facade 
supports  dynamic  methods,  meaning  you  may  call  any  Redis  command186  on  the  facade  and  the 
command  will  be  passed  directly  to  Redis.  In  this  example,  we  will  call  the  GET  command  on  Redis 
by  calling  the  get  method  on  the  Redis  facade: 


1 < ?php 

2 

3 namespace  App\Http\Control lers; 

4 

5 use  Redis; 

6 use  App\Http\Controllers\Controller; 

7 

8 class  UserController  extends  Controller 

9 { 

10  /** 

11  * Show  the  profile  for  the  given  user. 

12  * 

13  * @param  int  $id 

14  * §return  Response 

15  */ 


185https://github.com/nrk/predis/wiki/Client-Options 

186http://redis.io/commands 
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16  public  function  showProf i le($id) 

17  { 

18  $user  = Redis :: get( ' user : prof i le lid) ; 

19 

return  view( 1 user . prof i le ' , [ user'  =>  $user]); 

21  } 

22  } 


Of  course,  as  mentioned  above,  you  may  call  any  of  the  Redis  commands  on  the  Redis  facade. 
Laravel  uses  magic  methods  to  pass  the  commands  to  the  Redis  server,  so  simply  pass  the  arguments 
the  Redis  command  expects: 

1 Redis :: set( ' name ' , 'Taylor'); 

2 

3 lvalues  = Redis :: lrange( ' names  1 , 5,  10); 


Alternatively,  you  may  also  pass  commands  to  the  server  using  the  command  method,  which  accepts 
the  name  of  the  command  as  its  first  argument,  and  an  array  of  values  as  its  second  argument: 


1 lvalues  = Redis :: command( ' lrange ' , ['name',  5,  10J); 


Using  Multiple  Redis  Connections 

You  may  get  a Redis  instance  by  calling  the  Redis : : connection  method: 
1 Iredis  = Redis :: connection( ) ; 


This  will  give  you  an  instance  of  the  default  Redis  server.  If  you  are  not  using  server  clustering,  you 
may  pass  the  server  name  to  the  connection  method  to  get  a specific  server  as  defined  in  your  Redis 
configuration: 


1 Iredis  = Redis :: connection( ' other ') ; 
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Pipelining  Commands 

Pipelining  should  be  used  when  you  need  to  send  many  commands  to  the  server  in  one  operation. 
The  pipeline  method  accepts  one  argument:  a Closure  that  receives  a Redis  instance.  You  may  issue 
all  of  your  commands  to  this  Redis  instance  and  they  will  all  be  executed  within  a single  operation: 

1 Redis :: pipel ine( function  ($pipe)  { 

2 for  ($i  = 0;  $i  < 1000;  $i++)  { 

$pipe- >set( "key : $i " , $i); 

4 } 

5 }); 


Pub /Sub 

Laravel  also  provides  a convenient  interface  to  the  Redis  publish  and  subscribe  commands.  These 
Redis  commands  allow  you  to  listen  for  messages  on  a given  “channel”.  You  may  publish  messages 
to  the  channel  from  another  application,  or  even  using  another  programming  language,  allowing 
easy  communication  between  applications  / processes. 

First,  let’s  setup  a listener  on  a channel  via  Redis  using  the  subscribe  method.  We  will  place  this 
method  call  within  an  Artisan  command  since  calling  the  subscribe  method  begins  a long-running 
process: 


1 < ?php 

2 

3 namespace  App\Console\Commands; 

4 

5 use  Redis; 

6 use  Illuminate\Console\Command; 

7 

8 class  RedisSubscribe  extends  Command 

9 { 

10  /** 

11  * The  name  and  signature  of  the  console  command. 

12  * 

13  * §var  string 

14  */ 

15  protected  $signature  = ' redis : subscribe ' ; 

16 
17 
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18  * The  console  command  description . 

19  * 

20  * §var  string 

21  */ 

protected  $description  = 'Subscribe  to  a Redis  channel'; 

23 

24  /** 

25  * Execute  the  console  command. 

26  * 

27  * §return  mixed 

28  */ 

29  public  function  handle() 

30  { 

Redis :: subscribe( [' test-channel  ] , function($message)  { 

32  echo  $message; 

33  }); 

34  } 

35  } 


Now,  we  may  publish  messages  to  the  channel  using  the  publish  method: 

1 Route :: get( ' publ ish ' , function  ()  { 

//  Route  logic  . . . 

3 

Redis :: publ ish( ' test-channel ' , json_encode( [ ' foo ' =>  ' bar ' ] ) ) ; 

5 }); 


Wildcard  Subscriptions 

Using  the  psubscribe  method,  you  may  subscribe  to  a wildcard  channel,  which  is  useful  for  catching 
all  messages  on  all  channels.  The  $channel  name  will  be  passed  as  the  second  argument  to  the 
provided  callback  Closure: 
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1 Redis :: psubscribe( ['*'] , function($message,  $channel)  { 
echo  $message; 

3 }); 

4 

5 Redis :: psubscribe( [ 1 users . *'] , function($message,  $channel)  { 

6 echo  $message; 

7 }); 


Session 


• Introduction 

• Basic  Usage  A>  - Flash  Data 

• Adding  Custom  Session  Drivers 


Introduction 

Since  HTTP  driven  applications  are  stateless,  sessions  provide  a way  to  store  information  about  the 
user  across  requests.  Laravel  ships  with  a variety  of  session  back-ends  available  for  use  through  a 
clean,  unified  API.  Support  for  popular  back-ends  such  as  Memcached187,  Redis188,  and  databases  is 
included  out  of  the  box. 


Configuration 

The  session  configuration  file  is  stored  at  config/session . php.  Be  sure  to  review  the  well  docu- 
mented options  available  to  you  in  this  file.  By  default,  Laravel  is  configured  to  use  the  file  session 
driver,  which  will  work  well  for  many  applications.  In  production  applications,  you  may  consider 
using  the  memcached  or  redis  drivers  for  even  faster  session  performance. 

The  session  driver  defines  where  session  data  will  be  stored  for  each  request.  Laravel  ships  with 
several  great  drivers  out  of  the  box: 

<div  class=”content-list”  markdown=”l”>  - file  - sessions  are  stored  in  storage/framework/ses- 
sions. - cookie  - sessions  are  stored  in  secure,  encrypted  cookies.  - database  - sessions  are  stored 
in  a database  used  by  your  application.  - memcached  / redis  - sessions  are  stored  in  one  of  these 
fast,  cache  based  stores.  - array  - sessions  are  stored  in  a simple  PHP  array  and  will  not  be  persisted 
across  requests.  </div> 


Note:  The  array  driver  is  typically  used  for  running  tests  to  prevent  session  data  from 
persisting. 


187http://memcached.org 

188http://redis.io 
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Driver  Prerequisites 

Database 

When  using  the  database  session  driver,  you  will  need  to  setup  a table  to  contain  the  session  items. 
Below  is  an  example  Schema  declaration  for  the  table: 


1 Schema :: create( ' sessions ' , function  (Stable)  { 
Stable- > string ( 1 id ' ) - >unique( ) ; 

Stable- > integer ( ' user_id ' )->nullable(); 
Stable- > string ( 1 ip_address 1 , 45) ->nul lable( ) ; 

5 Stable- > text ( ' user_agent 1 )->nullable(); 

6 Stable- >text( ' payload ') ; 

Stable- > integer ( ’ last_activity 1 ) ; 

8 }); 


You  may  use  the  session : table  Artisan  command  to  generate  this  migration  for  you! 

1 php  artisan  session : table 

2 

3 composer  dump-autoload 

4 

5 php  artisan  migrate 


Redis 

Before  using  Redis  sessions  with  Laravel,  you  will  need  to  install  the  predi s/pred  is  package  (~1.0) 
via  Composer. 


Other  Session  Considerations 

The  Laravel  framework  uses  the  flash  session  key  internally,  so  you  should  not  add  an  item  to  the 
session  by  that  name. 

If  you  need  all  stored  session  data  to  be  encrypted,  set  the  encrypt  configuration  option  to  true. 
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Basic  Usage 

Accessing  The  Session 

First,  let’s  access  the  session.  We  can  access  the  session  instance  via  the  HTTP  request,  which  can 
be  type-hinted  on  a controller  method.  Remember,  controller  method  dependencies  are  injected  via 
the  Laravel  service  container: 


1 < ?php 

2 

3 namespace  App\Http\Control lers; 

4 

5 use  1 1 luminate\Http\Request; 

6 use  App\Http\Controllers\Controller; 

7 

8 class  UserController  extends  Controller 

9 { 

10  /** 

11  * Show  the  profile  for  the  given  user. 

12  * 

13  * §param  Request  $request 

14  * §param  int  $id 

15  * §return  Response 

16  */ 

17  public  function  showProfile(Request  $request,  $id) 

18  { 

19  $value  = $request- >session( ) - >get( ' key ' ) ; 

20 

21  // 

22  } 

23  } 


When  you  retrieve  a value  from  the  session,  you  may  also  pass  a default  value  as  the  second 
argument  to  the  get  method.  This  default  value  will  be  returned  if  the  specified  key  does  not  exist 
in  the  session.  If  you  pass  a Closure  as  the  default  value  to  the  get  method,  the  Closure  will  be 
executed  and  its  result  returned: 
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1 lvalue  = Irequest- >session( )- >get( ' key ' , 'default'); 

2 

3 lvalue  = Irequest- >session( ) - >get( ' key ' , function()  { 

4 return  'default'; 

5 }); 


If  you  would  like  to  retrieve  all  data  from  the  session,  you  may  use  the  all  method: 


1 Idata  = |request->session( ) ->al 1 ( ) ; 


You  may  also  use  the  global  session  PHP  function  to  retrieve  and  store  data  in  the  session: 


1 Route :: get( ' home ' , function  ()  { 

//  Retrieve  a piece  of  data  from  the  session. . . 
lvalue  = session( ' key ' ) ; 

4 

//  Store  a piece  of  data  in  the  session. . . 

6 session( [ ' key ' =>  'value']); 

7 }); 


Determining  If  An  Item  Exists  In  The  Session 

The  has  method  may  be  used  to  check  if  an  item  exists  in  the  session.  This  method  will  return  true 
if  the  item  exists: 


1 if  (Irequest- >session( )- >has( ' users ') ) { 

2 // 

3 } 


Storing  Data  In  The  Session 

Once  you  have  access  to  the  session  instance,  you  may  call  a variety  of  functions  to  interact  with 
the  underlying  data.  For  example,  the  put  method  stores  a new  piece  of  data  in  the  session: 
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1 $request->session( )->put( 'key  1 , 'value'); 


Pushing  To  Array  Session  Values 

The  push  method  may  be  used  to  push  a new  value  onto  a session  value  that  is  an  array.  For  example, 
if  the  user . teams  key  contains  an  array  of  team  names,  you  may  push  a new  value  onto  the  array 
like  so: 

1 $request->session( )->push( 'user .teams' , 'developers'); 


Retrieving  And  Deleting  An  Item 

The  pull  method  will  retrieve  and  delete  an  item  from  the  session: 
1 lvalue  = Irequest- >session( ) - >pul 1 ( ' key ' , 'default'); 


Deleting  Items  From  The  Session 

The  forget  method  will  remove  a piece  of  data  from  the  session.  If  you  would  like  to  remove  all 
data  from  the  session,  you  may  use  the  flush  method: 


1 $request->session( )->forget( 'key' ) ; 

2 

3 $request->session( ) - > f lush( ) ; 


Regenerating  The  Session  ID 

If  you  need  to  regenerate  the  session  ID,  you  may  use  the  regenerate  method: 
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1 $request->session( ) - >regenerate( ) ; 


Flash  Data 

Sometimes  you  may  wish  to  store  items  in  the  session  only  for  the  next  request.  You  may  do  so 
using  the  flash  method.  Data  stored  in  the  session  using  this  method  will  only  be  available  during 
the  subsequent  HTTP  request,  and  then  will  be  deleted.  Flash  data  is  primarily  useful  for  short-lived 
status  messages: 


1 $request->session( )->flash( 'status' , 'Task  was  successful!'); 


If  you  need  to  keep  your  flash  data  around  for  even  more  requests,  you  may  use  the  reflash  method, 
which  will  keep  all  of  the  flash  data  around  for  an  additional  request.  If  you  only  need  to  keep  specific 
flash  data  around,  you  may  use  the  keep  method: 

1 $request->session( )->reflash( ); 

2 

3 $request->session( )->keep( [ 'username' , 'email']); 


Adding  Custom  Session  Drivers 

To  add  additional  drivers  to  Laravel’s  session  back-end,  you  may  use  the  extend  method  on  the 
Session  facade.  You  can  call  the  extend  method  from  the  boot  method  of  a service  provider: 


1 < ?php 

2 

3 namespace  App\Providers; 

4 

5 use  Session; 

6 use  App\Extensions\MongoSessionStore; 

7 use  1 1 luminate\Support\ServiceProvider ; 

8 

9 class  SessionServiceProvider  extends  ServiceProvider 

10  { 
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11  /** 

12  * Perform  post-registration  booting  of  services. 

13  * 

14  * §return  void 

15  */ 

16  public  function  boot() 

17  { 

Session extend( ' mongo ' , function($app)  { 

19  //  Return  implementation  of  SessionHandlerlnterface. . . 

20  return  new  MongoSessionStore; 

21  }); 

22  } 

23 

24  /** 

25  * Register  bindings  in  the  container . 

26  * 

27  * §return  void 

28  */ 

29  public  function  registerQ 

30  { 

31  // 

32  } 

33  } 


Note  that  your  custom  session  driver  should  implement  the  SessionHandlerlnterface.  This  inter- 
face contains  just  a few  simple  methods  we  need  to  implement.  A stubbed  MongoDB  implementation 
looks  something  like  this: 


1 

2 

<?php 

3 

4 

namespace  App\Extensions; 

5 

class  MongoHandler  implements  SessionHandlerlnterface 

6 

{ 

7 

public 

function  open($savePath,  SsessionName)  {} 

8 

public 

function  closeQ  {} 

9 

public 

function  read($sessionId)  {} 

10 

public 

function  write($sessionId,  $data)  {} 

11 

public 

function  destroy($sessionId)  {} 

12 

public 

function  gc($l i fetime)  {} 

13 

} 
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Since  these  methods  are  not  as  readily  understandable  as  the  cache  Store  Inter  face,  let’s  quickly 
cover  what  each  of  the  methods  do: 

<div  class=”content-list”  markdown=”l”>  - The  open  method  would  typically  be  used  in  file  based 
session  store  systems.  Since  Laravel  ships  with  a file  session  driver,  you  will  almost  never  need 
to  put  anything  in  this  method.  You  can  leave  it  as  an  empty  stub.  It  is  simply  a fact  of  poor 
interface  design  (which  we’ll  discuss  later)  that  PHP  requires  us  to  implement  this  method.  - The 
close  method,  like  the  open  method,  can  also  usually  be  disregarded.  For  most  drivers,  it  is  not 
needed.  - The  read  method  should  return  the  string  version  of  the  session  data  associated  with  the 
given  $sessionId.  There  is  no  need  to  do  any  serialization  or  other  encoding  when  retrieving  or 
storing  session  data  in  your  driver,  as  Laravel  will  perform  the  serialization  for  you.  - The  write 
method  should  write  the  given  $data  string  associated  with  the  $sessionId  to  some  persistent 
storage  system,  such  as  MongoDB,  Dynamo,  etc.  - The  destroy  method  should  remove  the  data 
associated  with  the  $sessionId  from  persistent  storage.  - The  gc  method  should  destroy  all  session 
data  that  is  older  than  the  given  $1  i fetime,  which  is  a UNIX  timestamp.  For  self-expiring  systems 
like  Memcached  and  Redis,  this  method  may  be  left  empty.  </div> 

Once  the  session  driver  has  been  registered,  you  may  use  the  mongo  driver  in  your  config/ses- 
sion . php  configuration  file. 
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Introduction 

Laravel  Envoy189  provides  a clean,  minimal  syntax  for  defining  common  tasks  you  run  on  your 
remote  servers.  Using  a Blade  style  syntax,  you  can  easily  setup  tasks  for  deployment,  Artisan 
commands,  and  more.  Currently,  Envoy  only  supports  the  Mac  and  Linux  operating  systems. 

Installation 

First,  install  Envoy  using  the  Composer  global  command: 

1 composer  global  require  " laravel/envoy=~l . 0" 


Make  sure  to  place  the  ~/ .composer/vendor/bin  directory  in  your  PATH  so  the  envoy  executable 
is  found  when  you  run  the  envoy  command  in  your  terminal. 

Updating  Envoy 

You  may  also  use  Composer  to  keep  your  Envoy  installation  up  to  date: 

1 composer  global  update 


189https://github.com/laravel/envoy 
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Writing  Tasks 

All  of  your  Envoy  tasks  should  be  defined  in  an  Envoy,  blade,  php  file  in  the  root  of  your  project. 
Here’s  an  example  to  get  you  started: 


1 @servers( [ ' web ' =>  ' user@192 . 168 . 1 . 1 ' ] ) 

2 

3 @task( ’ foo ' , [on'  =>  'web']) 

4 Is  -la 

5 §endtask 


As  you  can  see,  an  array  of  @servers  is  defined  at  the  top  of  the  file,  allowing  you  to  reference  these 
servers  in  the  on  option  of  your  task  declarations.  Within  your  @task  declarations,  you  should  place 
the  Bash  code  that  will  be  run  on  your  server  when  the  task  is  executed. 

Bootstrapping 


Sometimes,  you  may  need  to  execute  some  PHP  code  before  evaluating  your  Envoy  tasks.  You  may 
use  the  @setup  directive  to  declare  variables  and  do  general  PHP  work  inside  the  Envoy  file: 


1 

@setup 

2 

$now  new  DateTime(); 

3 

4 

$environment  isset($env)  ? $env  : 

"testing" ; 

5 

@endsetup 

You  may  also  use  @include  to  include  any  outside  PHP  files: 


1 @include( ' vendor/autoload . php ' ) 


Confirming  Tasks 

If  you  would  like  to  be  prompted  for  confirmation  before  running  a given  task  on  your  servers,  you 
may  add  the  confirm  directive  to  your  task  declaration: 
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1 @task( ' deploy ' , ['on'  =>  'web',  'confirm'  =>  true]) 
cd  site 

git  pull  origin  {{  $branch  }} 

4 php  artisan  migrate 

5 @endtask 


Task  Variables 

If  needed,  you  may  pass  variables  into  the  Envoy  file  using  command  line  switches,  allowing  you 
to  customize  your  tasks: 

1 envoy  run  deploy  - -branch=master 


You  may  use  the  options  in  your  tasks  via  Blade’s  “echo”  syntax: 


1 

@servers( [ ' web ' 

=>  '192.168.1.1'] 

2 

3 

@task( ' deploy ' , 

[ ' on ' =>  ' web  ] ) 

4 

cd  site 

5 

git  pull  origin  {{  $branch  }} 

6 

php  artisan 

migrate 

7 

@endtask 

Multiple  Servers 

You  may  easily  run  a task  across  multiple  servers.  First,  add  additional  servers  to  your  ©servers 
declaration.  Each  server  should  be  assigned  a unique  name.  Once  you  have  defined  your  additional 
servers,  simply  list  the  servers  in  the  task  declaration’s  on  array: 
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1 @servers( [' web-1 ' =>  '192.168.1.1',  'web-2'  =>  '192.168.1.2']) 

2 

3 @task( ' deploy ' , ['on'  =>  [ web-1',  'web-2']]) 

4 cd  site 

5 git  pull  origin  {{  $branch  }} 

6 php  artisan  migrate 

7 @endtask 


By  default,  the  task  will  be  executed  on  each  server  serially.  Meaning,  the  task  will  finish  running 
on  the  first  server  before  proceeding  to  execute  on  the  next  server. 

Parallel  Execution 

If  you  would  like  to  run  a task  across  multiple  servers  in  parallel,  add  the  parallel  option  to  your 
task  declaration: 


1 @servers( [ ' web-1 ' =>  '192.168.1.1',  'web-2'  =>  '192.168.1.2']) 

2 

3 @task( ' deploy ' , ['on'  =>  [ web-1',  'web-2'],  'parallel'  =>  true]) 

4 cd  site 

5 git  pull  origin  {{  $branch  }} 

6 php  artisan  migrate 

7 @endtask 


Task  Macros 

Macros  allow  you  to  define  a set  of  tasks  to  be  run  in  sequence  using  a single  command.  For  instance, 
a deploy  macro  may  run  the  git  and  composer  tasks: 

1 §servers( [ ' web ' =>  '192.168.1.1']) 

2 

3 @macro( ' deploy ' ) 

4 git 

5 composer 

6 @endmacro 

7 

8 @task('git') 

9 git  pull  origin  master 

10  @endtask 
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11 

12  @task( ' composer ' ) 

composer  i nsta 1 1 
14  @endtask 


Once  the  macro  has  been  defined,  you  may  run  it  via  single,  simple  command: 
1 envoy  run  deploy 


Running  Tasks 

To  run  a task  from  your  Envoy . blade . php  file,  execute  Envoy’s  run  command,  passing  the  command 
the  name  of  the  task  or  macro  you  would  like  to  execute.  Envoy  will  run  the  task  and  display  the 
output  from  the  servers  as  the  task  is  running: 

1 envoy  run  task 


<a  name=”envoy-notifications”></a>  ##  Notifications  {#envoy-envoy-hipchat-notifications} 

HipChat 

After  running  a task,  you  may  send  a notification  to  your  team’s  HipChat  room  using  Envoy’s 
@hipchat  directive.  The  directive  accepts  an  API  token,  the  name  of  the  room,  and  the  username  to 
be  displayed  as  the  sender  of  the  message: 


1 @servers( [ ' web ' =>  '192.168.1.1']) 

2 

3 @task( ' foo ' , [on1 2 3 4 5 6 7  =>  'web']) 

4 Is  -la 

5 @endtask 

6 

7 @after 

§hipchat( ' token ' , 'room',  'Envoy') 
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9 ©endafter 


If  you  wish,  you  may  also  pass  a custom  message  to  send  to  the  HipChat  room.  Any  variables 
available  to  your  Envoy  tasks  will  also  be  available  when  constructing  the  message: 


1 

©after 

2 

@hipchat( ' token ' , 

' room ' , 

' Envoy ' , 

"{{  $task  }}  ran  in  the  {{  $env  }}  enviro\ 

3 

nment . " ) 

4 

©endafter 

Slack 

In  addition  to  HipChat,  Envoy  also  supports  sending  notifications  to  Slack190.  The  @slack  directive 
accepts  a Slack  hook  URL,  a channel  name,  and  the  message  you  wish  to  send  to  the  channel: 

1 ©after 

@slack( ' hook ' , 'channel',  'message') 

3 @endafter 


You  may  retrieve  your  webhook  URL  by  creating  an  Incoming  WebHooks  integration  on  Slack’s 
website.  The  hook  argument  should  be  the  entire  webhook  URL  provided  by  the  Incoming  Webhooks 
Slack  Integration.  Lor  example: 


1 https : //hooks .slack . com/services/ZZZZZZZZZ/YYYYYYYYY/XXXXXXXXXXXXXXX 


You  may  provide  one  of  the  following  as  the  channel  argument: 

• To  send  the  notification  to  a channel:  #channel 

• To  send  the  notification  to  a user:  §user 


190 


https://slack.com 
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Introduction 

In  the  past,  developers  have  generated  a Cron  entry  for  each  task  they  need  to  schedule.  However,  this 
is  a headache.  Your  task  schedule  is  no  longer  in  source  control,  and  you  must  SSH  into  your  server 
to  add  the  Cron  entries.  The  Laravel  command  scheduler  allows  you  to  fluently  and  expressively 
define  your  command  schedule  within  Laravel  itself,  and  only  a single  Cron  entry  is  needed  on  your 
server. 

Your  task  schedule  is  defined  in  the  app/Console/Kernel . php  file’s  schedule  method.  To  help  you 
get  started,  a simple  example  is  included  with  the  method.  You  are  free  to  add  as  many  scheduled 
tasks  as  you  wish  to  the  Schedule  object. 

Starting  The  Scheduler 

Here  is  the  only  Cron  entry  you  need  to  add  to  your  server: 


1 *****  php  /path/to/artisan  schedule: run  >>  /dev/null  2>&1 


This  Cron  will  call  the  Laravel  command  scheduler  every  minute.  Then,  Laravel  evaluates  your 
scheduled  tasks  and  runs  the  tasks  that  are  due. 

Defining  Schedules 

You  may  define  all  of  your  scheduled  tasks  in  the  schedule  method  of  the  App\Console\Kernel 
class.  To  get  started,  let’s  look  at  an  example  of  scheduling  a task.  In  this  example,  we  will  schedule 
a Closure  to  be  called  every  day  at  midnight.  Within  the  Closure  we  will  execute  a database  query 
to  clear  a table: 
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1 < ?php 

2 

3 namespace  App\Console; 

4 

5 use  DB; 

6 use  1 1 luminate\Console\Schedul ing\Schedule; 

7 use  1 1 luminate\Foundation\Console\Kernel  as  Consol eKernel ; 

8 

9 class  Kernel  extends  ConsoleKernel 

10  { 

11  /** 

12  * The  Artisan  commands  provided  by  your  application. 

13  * 

14  * @var  array 

15  */ 

16  protected  Scommands  = [ 

17  \App\Console\Commands\Inspire : :class, 

18  ]; 

19 

20  /** 

21  * Define  the  application's  command  schedule . 

22  * 

* §param  \llluminate\Console\Scheduling\Schedule  $schedule 

24  * § return  void 

25  */ 

protected  function  schedule(Schedule  Sschedule) 

27  { 

28  Sschedule- >cal 1 ( function  ()  { 

DB : : table( ' recent_users ' ) - >delete( ) ; 

30  } ) - >dai ly( ) ; 

31  } 

32  } 


In  addition  to  scheduling  Closure  calls,  you  may  also  schedule  Artisan  commands  and  operating 
system  commands.  For  example,  you  may  use  the  command  method  to  schedule  an  Artisan  command: 

1 Sschedule- >command( ' emai Is : send  -- force  1 ) ->daily( ) ; 


The  exec  command  may  be  used  to  issue  a command  to  the  operating  system: 
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1 $schedule- >exec( ' node  /home/forge/scr ipt . js ' ) - >dai ly( ) ; 


Schedule  Frequency  Options 

Of  course,  there  are  a variety  of  schedules  you  may  assign  to  your  task: 

Method  | Description | ->cron('*  * * * * *■);  | Run  the  task  on  a custom  Cron 

schedule  ->everyMinute( ) ; | Run  the  task  every  minute  - >everyFiveMinutes( ) ; | Run  the  task  ev- 
ery five  minutes  - >everyTenMinutes( ) ; | Run  the  task  every  ten  minutes  - >everyThirtyMinutes( ) ; 

| Run  the  task  every  thirty  minutes  ->hourly( );  | Run  the  task  every  hour  ->daily( );  | Run  the 
task  every  day  at  midnight  - >dai  lyAt(  '13:00');  | Run  the  task  every  day  at  13:00  - >twiceDai  ly(l , 
13);  | Run  the  task  daily  at  1:00  & 13:00 ->weekly( );  | Run  the  task  every  week  - >monthly( ) ; | Run 
the  task  every  month  - > quarter  1 y ( ) ; | Run  the  task  every  quarter  - > year  1 y ( ) ; | Run  the  task  every 
year ->timezone( ' America/New_York ' );  | Set  the  timezone 

These  methods  may  be  combined  with  additional  constraints  to  create  even  more  finely  tuned 
schedules  that  only  run  on  certain  days  of  the  week.  For  example,  to  schedule  a command  to  run 
weekly  on  Monday: 


1 $schedule->call(function  ()  { 

//  Runs  once  a week  on  Monday  at  13:00. . . 
3 } ) - > weekly ( ) - >mondays( ) - >at( '13:00' ) ; 


Below  is  a list  of  the  additional  schedule  constraints: 

Method  | Description | > weekdays ( ) ; | Limit  the  task  to  weekdays  - > Sundays ( ) ; 

| Limit  the  task  to  Sunday  ->mondays();  | Limit  the  task  to  Monday  ->tuesdays( );  | Limit  the 
task  to  Tuesday  ->  Wednesdays ( ) ; | Limit  the  task  to  Wednesday  ->thursdays( ) ; | Limit  the  task 
to  Thursday  - > fr idays( ) ; | Limit  the  task  to  Friday  - > Saturdays ( ) ; | Limit  the  task  to  Saturday 
->when(Closure) ; | Limit  the  task  based  on  a truth  test 

Truth  Test  Constraints 

The  when  method  may  be  used  to  limit  the  execution  of  a task  based  on  the  result  of  a given  truth 
test.  In  other  words,  if  the  given  Closure  returns  true,  the  task  will  execute  as  long  as  no  other 
constraining  conditions  prevent  the  task  from  running: 
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1 Sschedule- >command( 1 emai Is : send ')- >dai ly( )- >when( function  ()  { 
return  true; 

3 }); 


The  reject  method  may  be  seen  as  the  inverse  of  when.  If  the  reject  method  returns  true,  the 
scheduled  task  will  not  be  executed: 

1 $schedule- >command( 1 emai Is : send ')- >dai ly( )- >reject( function  ()  { 
return  true; 

3 }); 


When  using  chained  when  methods,  the  scheduled  command  will  only  execute  if  all  when  conditions 
return  true. 

Preventing  Task  Overlaps 

By  default,  scheduled  tasks  will  be  run  even  if  the  previous  instance  of  the  task  is  still  running.  To 
prevent  this,  you  may  use  the  withoutOver lapping  method: 


1 Sschedule- > command ( 1 emails : send ' ) - > withoutOver lapping ( ) ; 


In  this  example,  the  emai  Is:  send  Artisan  command  will  be  run  every  minute  if  it  is  not  already 
running.  The  withoutOverlapping  method  is  especially  useful  if  you  have  tasks  that  vary  drastically 
in  their  execution  time,  preventing  you  from  predicting  exactly  how  long  a given  task  will  take. 

Task  Output 

The  Laravel  scheduler  provides  several  convenient  methods  for  working  with  the  output  generated 
by  scheduled  tasks.  First,  using  the  sendOutputTo  method,  you  may  send  the  output  to  a file  for  later 
inspection: 


1 Sschedule- >command( 1 emai Is : send ' ) 
- >dai ly( ) 
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- >sendOutputTo($f i lePath) ; 


If  you  would  like  to  append  the  output  to  a given  file,  you  may  use  the  appendOutputTo  method: 


1 Sschedule- > command ( 1 2 * 4 5 emai Is : send ' ) 

2 ->daily() 
->appendOutputTo($filePath) ; 


Using  the  emai  lOutputTo  method,  you  may  e-mail  the  output  to  an  e-mail  address  of  your  choice. 
Note  that  the  output  must  first  be  sent  to  a file  using  the  sendOutputTo  method.  Also,  before  e- 
mailing  the  output  of  a task,  you  should  configure  Laravel’s  e-mail  services: 

1 Sschedule- >command( ' foo ' ) 

2 ->daily() 

- >sendOutputTo($fi lePath) 

4 - >emai 10utputTo( ' foo@example . com ' ) ; 


Note:  The  emai  lOutputTo  and  sendOutputTo  methods  are  exclusive  to  the  command  method 
and  are  not  supported  for  call. 


Task  Hooks 

Using  the  before  and  after  methods,  you  may  specify  code  to  be  executed  before  and  after  the 
scheduled  task  is  complete: 


1 Sschedule- >command( 1 emai Is : send ' ) 

2 ->daily() 

->before( function  ()  { 

4 //  Task  is  about  to  start. . . 

5 }) 

- >after( function  ()  { 

//  Task  is  complete. . . 
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8 }); 

Pinging  URLs 

Using  the  pingBefore  and  thenPing  methods,  the  scheduler  can  automatically  ping  a given  URL 
before  or  after  a task  is  complete.  This  method  is  useful  for  notifying  an  external  service,  such  as 
Laravel  Envoyer191,  that  your  scheduled  task  is  commencing  or  complete: 


1 $schedule- > command ( 1 emai Is : send ' ) 

2 ->daily() 

->pingBefore($url ) 

4 - >thenPing($url ) ; 

Using  either  the  pingBefore($url ) or  thenPing($url ) feature  requires  the  Guzzle  HTTP  library 
You  can  add  Guzzle  to  your  project  by  adding  the  following  line  to  your  composer . json  file: 


1 "guzzlehttp/guzzle" : "~5.3|~6.0" 

191i  ..  o ,,  ^ • 

https://envoyer.io 
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Introduction 

Laravel  is  built  with  testing  in  mind.  In  fact,  support  for  testing  with  PHPUnit  is  included  out  of  the 
box,  and  a phpunit.xml  file  is  already  setup  for  your  application.  The  framework  also  ships  with 
convenient  helper  methods  allowing  you  to  expressively  test  your  applications. 

An  ExampleTest . php  file  is  provided  in  the  tests  directory.  After  installing  a new  Laravel 
application,  simply  run  phpunit  on  the  command  line  to  run  your  tests. 

Test  Environment 

When  running  tests,  Laravel  will  automatically  set  the  configuration  environment  to  testing. 
Laravel  automatically  configures  the  session  and  cache  to  the  array  driver  while  testing,  meaning 
no  session  or  cache  data  will  be  persisted  while  testing. 

You  are  free  to  create  other  testing  environment  configurations  as  necessary.  The  testing  environ- 
ment variables  may  be  configured  in  the  phpunit . xml  file. 

Defining  & Running  Tests 

To  create  a new  test  case,  use  the  make : test  Artisan  command: 

1 php  artisan  make: test  UserTest 


This  command  will  place  a new  UserTest  class  within  your  tests  directory.  You  may  then  define 
test  methods  as  you  normally  would  using  PHPUnit.  To  run  your  tests,  simply  execute  the  phpunit 
command  from  your  terminal: 
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1 < ?php 

2 

3 use  1 1 luminate\Foundation\Testing\WithoutMiddleware; 

4 use  1 1 luminateXFoundationYFestingXDatabaseMigrations; 

5 use  Illuminate\Foundation\Testing\DatabaseTransactions; 

6 

7 class  UserTest  extends  TestCase 

8 { 

g /** 

10  * A basic  test  example. 

11  * 

12  * §return  void 

13  */ 

14  public  function  testExample( ) 

15  { 

16  Sthis- >assertTrue(true) ; 

17  } 

18  } 


Note:  If  you  define  your  own  setup  method  within  a test  class,  be  sure  to  call 
parent : : setUp. 


Application  Testing 

Laravel  provides  a very  fluent  API  for  making  HTTP  requests  to  your  application,  examining  the 
output,  and  even  filling  out  forms.  For  example,  take  a look  at  the  Examp leTest . php  fde  included  in 
your  tests  directory: 

1 < ?php 

2 

3 use  1 1 luminateXFoundationYTestingXWithoutMiddleware; 

4 use  Illuminate\Foundation\Testing\DatabaseTransactions; 

5 

6 class  ExampleTest  extends  TestCase 

7 { 

8 /** 

9 * A basic  functional  test  example. 

10  * 


Testing 


435 


11  * §return  void 

12  */ 

13  public  function  testBasicExample( ) 

14  { 

15  Sthis- >visit( ' / ' ) 

16  - >see( 1 2 * 4 5 6 Laravel  5') 

17  - >dontSee( ' Rai Is  1 ) ; 

18  } 

19  } 


The  visit  method  makes  a GET  request  into  the  application.  The  see  method  asserts  that  we  should 
see  the  given  text  in  the  response  returned  by  the  application.  The  dontSee  method  asserts  that  the 
given  text  is  not  returned  in  the  application  response.  This  is  the  most  basic  application  test  available 
in  Laravel. 

Interacting  With  Your  Application 

Of  course,  you  can  do  much  more  than  simply  assert  that  text  appears  in  a given  response.  Let’s  take 
a look  at  some  examples  of  clicking  links  and  filling  out  forms: 

Clicking  Links 

In  this  test,  we  will  make  a request  to  the  application,  “click”  a link  in  the  returned  response,  and 
then  assert  that  we  landed  on  a given  URL  For  example,  let’s  assume  there  is  a link  in  our  response 
that  has  a text  value  of  “About  Us”: 


1 <a  href="/about-us">About  Us</a> 


Now,  let’s  write  a test  that  clicks  the  link  and  asserts  the  user  lands  on  the  correct  page: 

1 public  function  testBasicExample( ) 

2 { 

$this- > visit( ' / ' ) 

4 - >cl ick( ' About  Us') 

5 - >seePageIs( ' /about-us ' ) ; 

6 } 
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Working  With  Forms 

Laravel  also  provides  several  methods  for  testing  forms.  The  type,  select,  check,  attach,  and  press 
methods  allow  you  to  interact  with  all  of  your  form’s  inputs.  For  example,  let’s  imagine  this  form 
exists  on  the  application’s  registration  page: 


1 <form  action="/register " method="POST" > 

{ ! ! csrf_f ield( ) ! ! } 

3 

4 <div> 

5 Name:  <input  type="text"  name="name"> 

6 </div> 

7 

8 <div> 

<input  type="checkbox"  value="yes"  name=" terms ">  Accept  Terms 

10  </div> 

11 

12  <div> 

13  <input  type="submit"  value="Register"> 

14  </div> 

15  </form> 


We  can  write  a test  to  complete  this  form  and  inspect  the  result: 


1 public  function  testNewllserRegistration( ) 

2 { 

$this- > visit( '/register' ) 

- >type( ' Taylor ' , 'name') 

- > check ( ' terms ' ) 

->press( 'Register' ) 

- >seePageIs( ' /dashboard ' ) ; 

8 } 


Of  course,  if  your  form  contains  other  inputs  such  as  radio  buttons  or  drop-down  boxes,  you  may 
easily  fill  out  those  types  of  fields  as  well.  Here  is  a list  of  each  form  manipulation  method: 

Method  | Description | $this->type($text,  $elementName)  | “Type”  text  into 

a given  field.  $th is ->select($ value,  $elementName)  | “Select”  a radio  button  or  drop-down 
field.  $this->check($elementName)  | “Check”  a checkbox  field.  $this->uncheck($elementName) 

| “Uncheck”  a checkbox  field.  $this->attach($pathToFile,  $elementName)  | “Attach”  a file  to  the 
form.  $this  - > press (SbuttonTextOrElementName)  | “Press”  a button  with  the  given  text  or  name. 
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Working  With  Attachments 

If  your  form  contains  file  input  types,  you  may  attach  files  to  the  form  using  the  attach  method: 


1 public  function  testPhotoCanBeUploaded( ) 

2 { 

$this- > visit( '/upload' ) 

->type('File  Name',  'name') 

5 ->attach($absolutePathToFile,  'photo') 

6 ->press( 'Upload' ) 

- >see( ' Upload  Successful!'); 

8 } 


TestingJSON  APIs 

Laravel  also  provides  several  helpers  for  testing  JSON  APIs  and  their  responses.  For  example,  the 
get,  post,  put,  patch,  and  delete  methods  may  be  used  to  issue  requests  with  various  HTTP  verbs. 
You  may  also  easily  pass  data  and  headers  to  these  methods.  To  get  started,  let’s  write  a test  to  make 
a POST  request  to  /user  and  assert  that  a given  array  was  returned  in  JSON  format: 

1 < ?php 

2 

3 class  ExampleTest  extends  TestCase 

4 { 

5 /** 

6 * A basic  functional  test  example. 

7 * 

8 * § return  void 

9 */ 

10  public  function  testBasicExample( ) 

11  { 

12  Sthis- >post( ' /user ' , ['name'  =>  'Sally']) 

13  ->seeJson([ 

14  'created'  =>  true, 

15  ]); 

16  } 

17  } 


The  seeJson  method  converts  the  given  array  into  JSON,  and  then  verifies  that  the  JSON  fragment 
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occurs  anywhere  within  the  entire  JSON  response  returned  by  the  application.  So,  if  there  are  other 
properties  in  the  JSON  response,  this  test  will  still  pass  as  long  as  the  given  fragment  is  present. 

Verify  Exact  JSON  Match 

If  you  would  like  to  verify  that  the  given  array  is  an  exact  match  for  the  JSON  returned  by  the 
application,  you  should  use  the  seeJsonEquals  method: 

1 < ?php 

2 

3 class  ExampleTest  extends  TestCase 

4 { 

5 /** 

6 * A basic  functional  test  example. 

7 * 

8 * § return  void 

9 */ 

10  public  function  testBasicExample( ) 

11  { 

12  $this- >post( ' /user ' , ['name'  =>  'Sally']) 

13  - >seeJsonEquals(  [ 

14  'created'  =>  true, 

15  ]); 

16  } 

17  } 


Verify  Structural  JSON  Match 

It  is  also  possible  to  verify  that  a JSON  response  adheres  to  a specific  structure.  For  this,  you  should 
use  the  seeJsonStructure  method  and  pass  it  a list  of  (nested)  keys: 


1 < ?php 

2 

3 class  ExampleTest  extends  TestCase 

4 { 

5 /** 

6 * A basic  functional  test  example. 

7 * 

8 * §return  void 

9 */ 

10  public  function  testBasicExample( ) 
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11 

12 

13 

14 

15 

16 

17 

18 

19 

20 


{ 

$this- >get( ' /user /l ' ) 

- >seeJsonStructure(  [ 

' name ' , 

'pet'  =>  [ 

' name ' , ' age ' 


]); 


} 


The  above  example  illustrates  an  expectation  of  receiving  a name  and  a nested  pet  object  with  its 
own  name  and  age.  seeJsonStructure  will  not  fail  if  additional  keys  are  present  in  the  response.  For 
example,  the  test  would  still  pass  if  the  pet  had  a weight  attribute. 

You  may  use  the  * to  assert  that  the  returned  JSON  structure  has  a list  where  each  list  item  contains 
at  least  the  attributes  found  in  the  set  of  values: 


1 < ?php 

2 

3 class  ExampleTest  extends  TestCase 

4 { 

5 /** 

6 * A basic  functional  test  example. 

7 * 

8 * @return  void 

9 */ 

10  public  function  testBasicExample( ) 

11  { 

12  //  Assert  that  each  user  in  the  list  has  at  least  an  id,  name  and  email  \ 

13  attribute. 

14  $this- >get( 1 /users ' ) 

15  - >seeJsonStructure( [ 

16  '*'  =>  [ 

17  ' id ' , ' name ' , ' emai 1 1 

18  ] 

19  ]); 

20  } 

21  } 


You  may  also  nest  the  * notation.  In  this  case,  we  will  assert  that  each  user  in  the  JSON  response 
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contains  a given  set  of  attributes  and  that  each  pet  on  each  user  also  contains  a given  set  of  attributes: 


1 

2 

3 

4 

5 

6 

7 

8 
9 

10 


$this- >get( ' /users ' ) 

->seeJsonStructure( [ 

'*'  =>  [ 

'id',  'name',  'email',  'pets'  =>  [ 

'*’  =>  [ 

' name ' , ' age ' 

] 

] 


]); 


Sessions  / Authentication 

Laravel  provides  several  helpers  for  working  with  the  session  during  testing.  First,  you  may  set  the 
session  data  to  a given  array  using  the  withSession  method.  This  is  useful  for  loading  the  session 
with  data  before  testing  a request  to  your  application: 

1 < ?php 

2 

3 class  ExampleTest  extends  TestCase 

4 { 

5 public  function  testAppl ication( ) 

6 { 

Sthis- >withSession( [ ' foo ' =>  'bar']) 

- >visit( ' / ' ) ; 

9 1 

10  } 


Of  course,  one  common  use  of  the  session  is  for  maintaining  user  state,  such  as  the  authenticated 
user.  The  actingAs  helper  method  provides  a simple  way  to  authenticate  a given  user  as  the  current 
user.  For  example,  we  may  use  a model  factory  to  generate  and  authenticate  a user: 
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1 < ?php 

2 

3 class  ExampleTest  extends  TestCase 

4 { 

5 public  function  testAppl ication( ) 

6 { 


7 


$user  = factory (App\User :: class) ->create( ) ; 


8 

9 


$this- >actingAs($user ) 

- >withSession( [ ' foo ' =>  'bar  ]) 
- >visit( 1 2 3 4 5 6 7 / ' ) 

- >see( 1 Hel lo,  ' . $user- >name) ; 


10 

11 


12 

13 

14 


} 


You  may  also  specify  which  guard  should  be  used  to  authenticate  the  given  user  by  passing  the 
guard  name  as  the  second  argument  to  the  actingAs  method: 


1 $this->actingAs($user,  'backend') 


When  testing  your  application,  you  may  find  it  convenient  to  disable  middleware  for  some  of  your 
tests.  This  will  allow  you  to  test  your  routes  and  controller  in  isolation  from  any  middleware 
concerns.  Laravel  includes  a simple  WithoutMiddleware  trait  that  you  can  use  to  automatically 
disable  all  middleware  for  the  test  class: 

1 < ?php 

2 

3 use  1 1 luminate\Foundation\Testing\WithoutMiddleware; 

4 use  Illuminate\Foundation\Testing\DatabaseTransactions; 

5 

6 class  ExampleTest  extends  TestCase 

7 { 

use  WithoutMiddleware; 


Disabling  Middleware 


9 


Testing 


442 


10  // 

11  } 


If  you  would  like  to  only  disable  middleware  for  a few  test  methods,  you  may  call  the  withoutMid- 
dleware  method  from  within  the  test  methods: 


1 < ?php 

2 

3 class  ExampleTest  extends  TestCase 


4 

{ 

5 

/** 

6 

* A basic  functional  test  example 

7 

* 

8 

* @return  void 

9 

*/ 

10 

public  function  testBasicExample( ) 

11 

{ 

12 

$this- >withoutMiddleware( ) ; 

13 

14 

$this- >visit( ' / ' ) 

15 

- >see( ' Laravel  5 1 2 * 4 ) ; 

16 

} 

17 

} 

Custom  HTTP  Requests 

If  you  would  like  to  make  a custom  HTTP  request  into  your  application  and  get  the  full  Illumi- 
nate\Http\Response  object,  you  may  use  the  call  method: 


1 public  function  testAppl ication( ) 

2 { 

$response  = $this- >cal 1 ( ' GET ' , 

4 

$this- >assertEquals(200,  $response- > status ( ) ) ; 

6 } 
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If  you  are  making  POST,  PUT,  or  PATCH  requests  you  may  pass  an  array  of  input  data  with  the  request. 
Of  course,  this  data  will  be  available  in  your  routes  and  controller  via  the  Request  instance: 


$response  = $this->call( 'POST' , '/user',  ['name'  =>  'Taylor']); 


PHPUnit  Assertions 

Laravel  provides  several  additional  assertion  methods  for  PHPUnit192  tests: 

Method  | Description | ->assertResponseOk( ) ; | Assert  that  the  client  response 

has  an  OK  status  code.  ->assertResponseStatus($code) ; | Assert  that  the  client  response  has  a 
given  code. ->assertViewHas($key,  $value  = null);  | Assert  that  the  response  view  has  a given 
piece  of  bound  data.  ->assertViewHasAll  (array  $bindings);  | Assert  that  the  view  has  a given 
list  of  bound  data.  ->assertViewMissing($key) ; | Assert  that  the  response  view  is  missing  a piece 
of  bound  data. ->assertRedirectedTo($uri,  $with  = []);  | Assert  whether  the  client  was  redi- 
rected to  a given  URI.  ->assertRedirectedToRoute($name,  $parameters  = [],  $with  = []);  | 
Assert  whether  the  client  was  redirected  to  a given  route.  ->assertRedirectedToAction($name, 
$parameters  = [],  $with  = []);  | Assert  whether  the  client  was  redirected  to  a given  ac- 
tion. ->assertSessionHas($key,  $value  = null);  | Assert  that  the  session  has  a given  value.  - 
>assertSessionHasAl  1 (array  $bindings);  | Assert  that  the  session  has  a given  list  of  values. 
->assertSessionHasErrors($bindings  = [],  $format  = null);  | Assert  that  the  session  has 
errors  bound.  ->assertHas01dInput( );  | Assert  that  the  session  has  old  input. 

Working  With  Databases 

Laravel  also  provides  a variety  of  helpful  tools  to  make  it  easier  to  test  your  database  driven 
applications.  First,  you  may  use  the  seelnDatabase  helper  to  assert  that  data  exists  in  the  database 
matching  a given  set  of  criteria.  For  example,  if  we  would  like  to  verify  that  there  is  a record  in  the 
users  table  with  the  email  value  of  sal ly@example . com,  we  can  do  the  following: 


1 

public  function  testDatabase( ) 

2 

{ 

3 

//  Make  call  to  application.. 

4 

5 

$this- >seeInDatabase( 'users' , 

['email'  =>  'sally@example.com']); 

6 

} 
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Of  course,  the  seelnDatabase  method  and  other  helpers  like  it  are  for  convenience.  You  are  free  to 
use  any  of  PHPUnit’s  built-in  assertion  methods  to  supplement  your  tests. 

Resetting  The  Database  After  Each  Test 

It  is  often  useful  to  reset  your  database  after  each  test  so  that  data  from  a previous  test  does  not 
interfere  with  subsequent  tests. 

Using  Migrations 

One  option  is  to  rollback  the  database  after  each  test  and  migrate  it  before  the  next  test.  Laravel 
provides  a simple  DatabaseMigrations  trait  that  will  automatically  handle  this  for  you.  Simply  use 
the  trait  on  your  test  class: 


1 < ?php 

2 

3 use  1 1 luminate\Foundation\Testing\WithoutMiddleware; 

4 use  1 1 luminate\Foundation\Testing\DatabaseMigrations; 

5 use  Illuminate\Foundation\Testing\DatabaseTransactions; 

6 

7 class  ExampleTest  extends  TestCase 

8 { 

use  DatabaseMigrations; 


10 


11 

12 

13 

14 

15 

16 
17 


/** 


* A basic  functional  test  example. 

* 

* §return  void 
*/ 

public  function  testBasicExample( ) 


18 

19 


$this- >visit( ' / ' ) 

- >see( 1 Laravel  5 1 ) ; 


20 

21 


Using  Transactions 

Another  option  is  to  wrap  every  test  case  in  a database  transaction.  Again,  Laravel  provides  a 
convenient  DatabaseTransactions  trait  that  will  automatically  handle  this: 
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1 < ?php 

2 

3 use  1 1 luminate\Foundation\Testing\WithoutMiddleware; 

4 use  1 1 luminateXFoundationYFestingXDatabaseMigrations; 

5 use  Illuminate\Foundation\Testing\DatabaseTransactions; 

6 

7 class  ExampleTest  extends  TestCase 

8 { 

9 use  DatabaseTransactions; 

10 

11  /** 

12  * A basic  functional  test  example. 

13  * 

14  * @return  void 

15  */ 

16  public  function  testBasicExample( ) 

17  { 

18  $this- >visit( ' / ' ) 

19  - >see( 1 Laravel  5'); 

20  } 

21  } 


Note:  This  trait  will  only  wrap  the  default  database  connection  in  a transaction. 


Model  Factories 

When  testing,  it  is  common  to  need  to  insert  a few  records  into  your  database  before  executing  your 
test.  Instead  of  manually  specifying  the  value  of  each  column  when  you  create  this  test  data,  Laravel 
allows  you  to  define  a default  set  of  attributes  for  each  of  your  Eloquent  models  using  “factories”. 
To  get  started,  take  a look  at  the  database/factories/ModelFactory.php  file  in  your  application. 
Out  of  the  box,  this  file  contains  one  factory  definition: 
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1 $factory->define(App\User : :class,  function  ( Faker \Generator  $faker)  { 
return  [ 


3 

4 

5 

6 
7 


name'  =>  $faker->name, 
email'  =>  Sfaker- >emai 1 , 
password'  =>  bcrypt(str_random(10) ) , 
remember_token ' =>  str_random(10) , 


8 }); 


Within  the  Closure,  which  serves  as  the  factory  definition,  you  may  return  the  default  test  values  of 
all  attributes  on  the  model.  The  Closure  will  receive  an  instance  of  the  Faker193  PHP  library,  which 
allows  you  to  conveniently  generate  various  kinds  of  random  data  for  testing. 

Of  course,  you  are  free  to  add  your  own  additional  factories  to  the  ModelFactory . php  file. 

Multiple  Factory  Types 

Sometimes  you  may  wish  to  have  multiple  factories  for  the  same  Eloquent  model  class.  For  example, 
perhaps  you  would  like  to  have  a factory  for  “Administrator”  users  in  addition  to  normal  users.  You 
may  define  these  factories  using  the  def  ineAs  method: 


1 $factory->defineAs(App\User : :class,  ’admin',  function  ($faker)  { 
return  [ 

'name'  =>  $faker- >name, 

4 'email'  =>  Sfaker- >emai 1 , 

5 'password'  =>  str_random(10) , 

6 ' remember_token ' =>  str_random(10) , 

7 'admin'  =>  true, 


Instead  of  duplicating  all  of  the  attributes  from  your  base  user  factory,  you  may  use  the  raw  method 
to  retrieve  the  base  attributes.  Once  you  have  the  attributes,  simply  supplement  them  with  any 
additional  values  you  require: 


8 


9 }) 
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1  Sfactory- >def ineAs( App\User : :class,  'admin' , function  ($faker)  use  ($factory)  { 
$user  = Sfactory- >raw(App\User :: class) ; 

3 

4 return  array_merge($user , /"'admin'  =>  truej); 

5 }); 


Using  Factories  In  Tests 

Once  you  have  defined  your  factories,  you  may  use  them  in  your  tests  or  database  seed  files  to 
generate  model  instances  using  the  global  factory  function.  So,  let’s  take  a look  at  a few  examples 
of  creating  models.  First,  we’ll  use  the  make  method,  which  creates  models  but  does  not  save  them 
to  the  database: 


1 public  function  testDatabase( ) 

2 { 

$user  = factory(App\User : class) - >make( ) ; 

4 

5 //  Use  model  in  tests. . . 

6 } 


If  you  would  like  to  override  some  of  the  default  values  of  your  models,  you  may  pass  an  array  of 
values  to  the  make  method.  Only  the  specified  values  will  be  replaced  while  the  rest  of  the  values 
remain  set  to  their  default  values  as  specified  by  the  factory: 


1 $user  = factory(App\User :: class) - >make( [ 
' name ' =>  ' Abigai 1 ' , 

3 ]); 


You  may  also  create  a Collection  of  many  models  or  create  models  of  a given  type: 
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1 //  Create  three  App\User  instances. . . 

2 $users  = factory (App\User : :class,  3)->make(); 

3 

4 //  Create  an  App\User  "admin"  instance... 

5 $user  = factory (App\User :: class,  ' admin ')- >make( ) ; 

6 

7 //  Create  three  App\User  "admin"  instances... 

8 $users  = factory (App\User :: class,  'admin',  3)->make(); 


Persisting  Factory  Models 

The  create  method  not  only  creates  the  model  instances,  but  also  saves  them  to  the  database  using 
Eloquent’s  save  method: 

1 public  function  testDatabase( ) 

2 { 

$user  = factory(App\User  : class) - >create( ) ; 

4 

5 //  Use  model  in  tests. . . 

6 } 


Again,  you  may  override  attributes  on  the  model  by  passing  an  array  to  the  create  method: 

1 $user  = factory(App\User :: class) - >create( [ 

' name  1 =>  ' Abigai 1 ' , 

3 ]); 


Adding  Relations  To  Models 

You  may  even  persist  multiple  models  to  the  database.  In  this  example,  we’ll  even  attach  a relation  to 
the  created  models.  When  using  the  create  method  to  create  multiple  models,  an  Eloquent  collection 
instance  is  returned,  allowing  you  to  use  any  of  the  convenient  functions  provided  by  the  collection, 
such  as  each: 
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1 

2 

3 

4 

5 


Susers  = factory (App\User : :class,  3) 

- >create( ) 

->each( function($u)  { 

$u-> posts ( ) ->save( factory ( App\Post . : class) - >make( ) ) ; 

}); 


Mocking 

Mocking  Events 

If  you  are  making  heavy  use  of  Laravel’s  event  system,  you  may  wish  to  silence  or  mock  certain 
events  while  testing.  For  example,  if  you  are  testing  user  registration,  you  probably  do  not  want  all 
of  a UserRegistered  event’s  handlers  firing,  since  these  may  send  “welcome”  e-mails,  etc. 

Laravel  provides  a convenient  expectsEvents  method  that  verifies  the  expected  events  are  fired,  but 
prevents  any  handlers  for  those  events  from  running: 


1 < ?php 

2 

3 class  ExampleTest  extends  TestCase 

4 { 

5 public  function  testUserRegistration( ) 

6 { 

Sthis- > expectsEvents ( App\Events\User Registered : : class) ; 

8 

9 //  Test  user  registration . . . 

10  } 

11  } 


You  may  use  the  doesntExpectEvents  method  to  verify  that  the  given  events  are  not  fired: 
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1 

<?php 

2 

3 

class  ExampleTest  extends  TestCase 

4 

{ 

5 

public  function  testPodcastPurchase( ) 

6 

{ 

7 

$this- >expectsEvents(App\Events\PodcastWasPurchased : : class) ; 

8 

9 

$this- >doesntExpectEvents(App\Events\PaymentWasDecl ined : 

class) ; 

10 

11 

//  Test  purchasing  podcast. . . 

12 

1 

13 

} 

If  you  would  like  to  prevent  all  event  handlers  from  running,  you  may 
method: 

use  the  withoutEvents 

l 

<?php 

2 

3 

class  ExampleTest  extends  TestCase 

4 

{ 

5 

public  function  testUserRegistration( ) 

6 

{ 

7 

Sthis- >withoutEvents( ) ; 

8 

9 

//  Test  user  registration  code. . . 

10 

1 

11 

} 

Mockingjobs 

Sometimes,  you  may  wish  to  simply  test  that  specific  jobs  are  dispatched  by  your  controllers  when 
making  requests  to  your  application.  This  allows  you  to  test  your  routes  / controllers  in  isolation  - 
set  apart  from  your  job’s  logic.  Of  course,  you  can  then  test  the  job  itself  in  a separate  test  class. 

Laravel  provides  a convenient  expectsJobs  method  that  will  verify  that  the  expected  jobs  are 
dispatched,  but  the  job  itself  will  not  be  executed: 
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1 < ?php 

2 

3 class  ExampleTest  extends  TestCase 

4 { 

5 public  function  testPurchasePodcast( ) 

6 { 

Sthis- >expectsJobs(App\Jobs\PurchasePodcast : : class) ; 

8 

9 //  Test  purchase  podcast  code.  . . 

10  } 

11  } 


Note:  This  method  only  detects  jobs  that  are  dispatched  via  the  DispatchesJobs  trait’s 
dispatch  methods  or  the  dispatch  helper  function.  It  does  not  detect  jobs  that  are  sent 
directly  to  Queue:  : push. 


Mocking  Facades 

When  testing,  you  may  often  want  to  mock  a call  to  a Laravel  facade.  For  example,  consider  the 
following  controller  action: 


1 < ?php 

2 

3 namespace  App\Http\Control lers; 

4 

5 use  Cache; 

6 

7 class  UserController  extends  Controller 

8 { 

9 /** 

10  * Show  a list  of  all  users  of  the  application. 

11  * 

12  * §return  Response 

13  */ 

14  public  function  index() 

15  { 

16  Svalue  = Cache :: get( ' key ') ; 

17 

18 


// 
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19 

20  } 


We  can  mock  the  call  to  the  Cache  facade  by  using  the  shouldReceive  method,  which  will  return 
an  instance  of  a Mockery194  mock.  Since  facades  are  actually  resolved  and  managed  by  the  Laravel 


service  container,  they  have  much  more  testability  than  a typical  static  class.  For  example,  let’s  mock 
our  call  to  the  Cache  facade: 

1 < ?php 

2 

3 class  FooTest  extends  TestCase 


4 

5 


public  function  testGet!ndex( ) 


6 

7 


Cache: : shouldReceive( 'get' ) 


8 

9 

10 

11 


- >once( ) 

- >with( ' key ' ) 

- >andReturn( 'value ' ) ; 


12 

13 

14 


$this- >visit( ' /users ' ) ->see( 'value ' ) ; 


© 


Note:  You  should  not  mock  the  Request  facade.  Instead,  pass  the  input  you  desire  into  the 
HTTP  helper  methods  such  as  cal  1 and  post  when  running  your  test. 


194 
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• Conditionally  Adding  Rules 
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Introduction 

Laravel  provides  several  different  approaches  to  validate  your  application’s  incoming  data.  By 
default,  Laravel’s  base  controller  class  uses  a Val  idatesRequests  trait  which  provides  a convenient 
method  to  validate  incoming  HTTP  request  with  a variety  of  powerful  validation  rules. 

Validation  Quickstart 

To  learn  about  Laravel’s  powerful  validation  features,  let’s  look  at  a complete  example  of  validating 
a form  and  displaying  the  error  messages  back  to  the  user. 

Defining  The  Routes 

First,  let’s  assume  we  have  the  following  routes  defined  in  our  app/Http/routes . php  file: 


1 //  Display  a form  to  create  a blog  post. . . 

2 Route :: get( ' post/create ' , ' PostControl ler§create ' ) ; 

3 

4 //  Store  a new  blog  post. . . 

5 Route :: post( ' post ' , ' PostControl ler@store 1 2 3 4 5 ) ; 


Of  course,  the  GET  route  will  display  a form  for  the  user  to  create  a new  blog  post,  while  the  POST 
route  will  store  the  new  blog  post  in  the  database. 
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Creating  The  Controller 

Next,  let’s  take  a look  at  a simple  controller  that  handles  these  routes.  We’ll  leave  the  store  method 
empty  for  now: 

1 < ?php 

2 

3 namespace  App\Http\Control lers; 

4 

5 use  1 1 luminate\Http\Request; 

6 use  App\Http\Controllers\Controller; 

7 

8 class  PostController  extends  Controller 

9 { 

10  /** 

11  * Show  the  form  to  create  a new  blog  post. 

12  * 

13  * §return  Response 

14  */ 

15  public  function  create() 

16  { 

17  return  view( 1 post . create ') ; 

18  } 

19 

20  /** 

21  * Store  a new  blog  post. 

22  * 

23  * §param  Request  $request 

24  * §return  Response 

25  */ 

public  function  store(Request  Srequest) 

27  { 

28  //  Validate  and  store  the  blog  post. . . 

29  } 

30  } 


Writing  The  Validation  Logic 

Now  we  are  ready  to  fill  in  our  store  method  with  the  logic  to  validate  the  new  blog  post.  If  you 
examine  your  application’s  base  controller  (App\Http\Control  lers\Control  ler)  class,  you  will  see 
that  the  class  uses  a Val idatesRequests  trait.  This  trait  provides  a convenient  validate  method  in 
all  of  your  controllers. 
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The  validate  method  accepts  an  incoming  HTTP  request  and  a set  of  validation  rules.  If  the 
validation  rules  pass,  your  code  will  keep  executing  normally;  however,  if  validation  fails,  an 
exception  will  be  thrown  and  the  proper  error  response  will  automatically  be  sent  back  to  the  user.  In 
the  case  of  a traditional  HTTP  request,  a redirect  response  will  be  generated,  while  a JSON  response 
will  be  sent  for  AJAX  requests. 

To  get  a better  understanding  of  the  validate  method,  let’s  jump  back  into  the  store  method: 


1 /** 

2 * Store  a new  blog  post. 

3 * 

4 * §param  Request  $request 

5 * §return  Response 

6 V 

7 public  function  store(Request  $request) 

8 { 

$this->validate($request,  [ 

10  'title'  =>  ' required  I unique : posts  I max : 255 ' , 

11  'body'  =>  'required', 

12  ]); 

13 

//  The  blog  post  is  valid,  store  in  database. . 

15  } 


As  you  can  see,  we  simply  pass  the  incoming  HTTP  request  and  desired  validation  rules  into  the 
validate  method.  Again,  if  the  validation  fails,  the  proper  response  will  automatically  be  generated. 
If  the  validation  passes,  our  controller  will  continue  executing  normally. 

Stopping  On  First  Validation  Failure 

Sometimes  you  may  wish  to  stop  running  validation  rules  on  an  attribute  after  the  first  validation 
failure.  To  do  so,  assign  the  bail  rule  to  the  attribute: 

1 $this->val idate($request,  [ 

'title'  =>  ' bai 1 I required  I unique : posts  I max : 255 ' , 

'body'  =>  'required', 

4 ]); 


In  this  example,  if  the  required  rule  on  the  title  attribute  fails,  the  unique  rule  will  not  be  checked. 
Rules  will  be  validated  in  the  order  they  are  assigned. 
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A Note  On  Nested  Attributes 


If  your  HTTP  request  contains  “nested”  parameters,  you  may  specify  them  in  your  validation  rules 
using  “dot”  syntax: 


1 $this->val idate($request,  [ 

'title'  =>  ' required  I unique : posts | max : 255 ' , 
' author . name ' =>  'required', 

' author . description ' =>  'required', 

5 ]); 


Displaying  The  Validation  Errors 

So,  what  if  the  incoming  request  parameters  do  not  pass  the  given  validation  rules?  As  mentioned 
previously,  Laravel  will  automatically  redirect  the  user  back  to  their  previous  location.  In  addition, 
all  of  the  validation  errors  will  automatically  be  flashed  to  the  session. 

Again,  notice  that  we  did  not  have  to  explicitly  bind  the  error  messages  to  the  view  in  our 
GET  route.  This  is  because  Laravel  will  check  for  errors  in  the  session  data,  and  automatically 
bind  them  to  the  view  if  they  are  available.  The  $errors  variable  will  be  an  instance  of  Illu- 
minate\Support\MessageBag.  For  more  information  on  working  with  this  object,  check  out  its 
documentation. 


Note:  The  $errors  variable  is  bound  to  the  view  by  the 

1 1 luminate\View\Middleware\ShareErrorsFromSession  middleware,  which  is  provided 
by  the  web  middleware  group.  When  this  middleware  is  applied  an  $errors  variable 
will  always  be  available  in  your  views,  allowing  you  to  conveniently  assume  the 
.terrors  variable  is  always  defined  and  can  be  safely  used. 


So,  in  our  example,  the  user  will  be  redirected  to  our  controller’s  create  method  when  validation 
fails,  allowing  us  to  display  the  error  messages  in  the  view: 
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1 <!--  /resources/views/post/create . blade . php  --> 

2 

3 <hl>Create  Post</hl> 

4 

5 §if  (count($errors)  > 0) 

6 <div  class="alert  alert-danger " > 

7 <ul> 

@foreach  ($errors- >al 1 ( ) as  $error) 
9 < 1 i > { { $error  }}</li> 

10  ©endforeach 

11  </ul> 

12  </div> 

13  @endif 

14 

15  <!--  Create  Post  Form  --> 


Customizing  The  Flashed  Error  Format 

If  you  wish  to  customize  the  format  of  the  validation  errors  that  are  flashed  to  the  session  when 
validation  fails,  override  the  formatVal idationErrors  on  your  base  controller.  Don’t  forget  to 
import  the  1 1 luminate\Contracts\Val  idation\Val  idator  class  at  the  top  of  the  file: 


1 < ?php 

2 

3 namespace  App\Http\Control lers; 

4 

5 use  Illuminate\Foundation\Bus\DispatchesJobs; 

6 use  Illuminate\Contracts\Validation\Validator; 

7 use  1 1 luminate\Routing\Control ler  as  BaseControl ler ; 

8 use  Illuminate\Foundation\Validation\ValidatesRequests; 

9 

10  abstract  class  Controller  extends  BaseControl ler 

11  { 

12  use  DispatchesJobs,  Val idatesRequests; 

13 

14  /** 

15  * { §inheritdoc } 

16  */ 

17  protected  function  formatVal idationErrors(Val idator  $val idator) 

18  { 

19 


return  $val idator- > errors ( ) - >all ( ) ; 
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20  } 
21  } 


AJAX  Requests  & Validation 

In  this  example,  we  used  a traditional  form  to  send  data  to  the  application.  However,  many 
applications  use  AJAX  requests.  When  using  the  validate  method  during  an  AJAX  request,  Laravel 
will  not  generate  a redirect  response.  Instead,  Laravel  generates  a JSON  response  containing  all  of 
the  validation  errors.  This  JSON  response  will  be  sent  with  a 422  HTTP  status  code. 

Validating  Arrays 

Validating  array  form  input  fields  doesn’t  have  to  be  a pain.  For  example,  to  validate  that  each  e-mail 
in  a given  array  input  field  is  unique,  you  may  do  the  following: 

1 $validator  = Validator : :make($request->all( ),  [ 

' person . *. emai 1 ' =>  ' emai 1 | unique : users ' 

3 ]); 


Likewise,  you  may  use  the  * character  when  specifying  your  validation  messages  in  your  language 
files,  making  it  a breeze  to  use  a single  validation  message  for  array  based  fields: 


1 'custom'  =>  [ 

' person . *. emai 1 ' =>  [ 

'unique'  =>  'Each  person  must  have  a unique  e-mail  address', 

4 ] 

5 ], 


Other  Validation  Approaches 

Manually  Creating  Validators 

If  you  do  not  want  to  use  the  Val idatesRequests  trait’s  validate  method,  you  may  create  a 
validator  instance  manually  using  the  Validator  facade.  The  make  method  on  the  facade  generates 
a new  validator  instance: 
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1 

2 

3 

4 

5 

6 

7 

8 
9 

10 

11 

12 

13 

14 

15 

16 

17 

18 

19 

20 
21 
22 

23 

24 

25 

26 

27 

28 

29 

30 

31 

32 


<?php 

namespace  App\Http\Control lers; 
use  Validator; 

use  1 1 luminate\Http\Request; 

use  App\Http\Control lers\Control ler ; 

class  PostController  extends  Controller 

{ 

/** 

* Store  a new  blog  post. 

* 

* §param  Request  $request 

* §return  Response 
*/ 

public  function  store(Request  $request) 

{ 

$validator  = Validator : :make($request->all( ),  [ 
'title'  =>  ' required | unique : posts  I max : 255 ' , 
'body'  =>  'required', 

]); 

if  ($val idator- > fails( ) ) { 

return  redirect( ' post/create ' ) 

- >withErrors($val idator) 

- >withlnput( ) ; 

} 

//  Store  the  blog  post. . . 

} 

} 


The  first  argument  passed  to  the  make  method  is  the  data  under  validation.  The  second  argument  is 
the  validation  rules  that  should  be  applied  to  the  data. 

After  checking  if  the  request  failed  to  pass  validation,  you  may  use  the  withErrors  method  to  flash 
the  error  messages  to  the  session.  When  using  this  method,  the  $errors  variable  will  automatically 
be  shared  with  your  views  after  redirection,  allowing  you  to  easily  display  them  back  to  the  user. 
The  withErrors  method  accepts  a validator,  a MessageBag,  or  a PHP  array. 
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Named  Error  Bags 

If  you  have  multiple  forms  on  a single  page,  you  may  wish  to  name  the  MessageBag  of  errors, 
allowing  you  to  retrieve  the  error  messages  for  a specific  form.  Simply  pass  a name  as  the  second 
argument  to  withErrors: 


1 return  redirect( ' register ' ) 

- > withErrors ($val idator , 'login  1 ) ; 


You  may  then  access  the  named  MessageBag  instance  from  the  $errors  variable: 
1 {{  $errors-> login- >first( 'email  1 ) }} 


After  Validation  Hook 

The  validator  also  allows  you  to  attach  callbacks  to  be  run  after  validation  is  completed.  This  allows 
you  to  easily  perform  further  validation  and  even  add  more  error  messages  to  the  message  collection. 
To  get  started,  use  the  a f ter  method  on  a validator  instance: 


1 $validator  = Validator: :make( . . . ); 

2 

3 $validator->after( function($validator)  { 

4 if  ($this- >somethingElseIsInval id( ) ) { 

5 $val idator->errors( )- >add( 1 field  1 , 'Something  is  wrong  with  this  field ! ' \ 

6 ); 

7 } 

8 }); 

9 

10  if  ($validator->fails( ) ) { 

11  // 

12  } 


Form  Request  Validation 

For  more  complex  validation  scenarios,  you  may  wish  to  create  a “form  request”.  Form  requests 
are  custom  request  classes  that  contain  validation  logic.  To  create  a form  request  class,  use  the 
make : request  Artisan  CLI  command: 
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1  php  artisan  make: request  StoreBlogPostRequest 


The  generated  class  will  be  placed  in  the  app/Http/Requests  directory.  Let’s  add  a few  validation 
rules  to  the  rules  method: 


1 /** 

2 * Get  the  validation  rules  that  apply  to  the  request. 

3 * 

4 * §return  array 

5 V 

6 public  function  rules() 
return  [ 

'title'  =>  ' required ] unique : posts  I max : 255 ' , 
'body'  =>  ’required’, 


7 { 

8 
9 

10 

11 

12  } 


So,  how  are  the  validation  rules  evaluated?  All  you  need  to  do  is  type-hint  the  request  on  your 
controller  method.  The  incoming  form  request  is  validated  before  the  controller  method  is  called, 
meaning  you  do  not  need  to  clutter  your  controller  with  any  validation  logic: 


1 /** 

2 * Store  the  incoming  blog  post. 

3 * 

4 * §param  StoreBlogPostRequest  $request 

5 * §return  Response 

6 V 

7 public  function  store(StoreBlogPostRequest  Srequest) 

8 { 

//  The  incoming  request  is  valid 

10  } 


If  validation  fails,  a redirect  response  will  be  generated  to  send  the  user  back  to  their  previous 
location.  The  errors  will  also  be  flashed  to  the  session  so  they  are  available  for  display.  If  the  request 
was  an  AJAX  request,  a HTTP  response  with  a 422  status  code  will  be  returned  to  the  user  including 
a JSON  representation  of  the  validation  errors. 
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Authorizing  Form  Requests 

The  form  request  class  also  contains  an  authorize  method.  Within  this  method,  you  may  check  if 
the  authenticated  user  actually  has  the  authority  to  update  a given  resource.  For  example,  if  a user 
is  attempting  to  update  a blog  post  comment,  do  they  actually  own  that  comment?  For  example: 


1 /** 

2 * Determine  if  the  user  is  authorized  to  make  this  request. 

3 * 

4 * @return  bool 

5 V 

6 public  function  authorize() 

7 { 

Scommentld  $this- >route( 1 2 3 4 5 6 7 comment ' ) ; 

9 

10  return  Comment  :where('id',  Scommentld) 

11  ->where( ' user_id ' , Auth : : id( ) ) - >exists( ) ; 

12  } 


Note  the  call  to  the  route  method  in  the  example  above.  This  method  grants  you  access  to  the  URI 
parameters  defined  on  the  route  being  called,  such  as  the  {comment}  parameter  in  the  example  below: 


1 Route : : post( ' comment/{comment} ' ) ; 


If  the  authorize  method  returns  false,  a HTTP  response  with  a 403  status  code  will  automatically 
be  returned  and  your  controller  method  will  not  execute. 

If  you  plan  to  have  authorization  logic  in  another  part  of  your  application,  simply  return  true  from 
the  authorize  method: 


1 /** 

2 * Determine  if  the  user  is  authorized  to  make  this  request. 

3 * 

4 * §return  bool 

5 */ 

6 public  function  authorizeQ 

7 { 

return  true; 

9 } 
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Customizing  The  Flashed  Error  Format 

If  you  wish  to  customize  the  format  of  the  validation  errors  that  are  flashed  to  the  session  when 
validation  fails,  override  the  formatErrors  on  your  base  request  (App\Http\Requests\Request). 
Don’t  forget  to  import  the  1 1 luminate\Contracts\Val  idation\Val  idator  class  at  the  top  of  the 
file: 


1  /** 

2 * {§i nheri tdoc } 

3 V 

4 protected  function  formatErrors (Val idator  $val idator) 

5 { 

return  $val idator- > errors ( ) - >al 1 ( ) ; 

7 } 


Customizing  The  Error  Messages 

You  may  customize  the  error  messages  used  by  the  form  request  by  overriding  the  messages  method. 
This  method  should  return  an  array  of  attribute  / rule  pairs  and  their  corresponding  error  messages: 

1 /** 

2 * Get  the  error  messages  for  the  defined  validation  rules. 

3 * 

4 * §return  array 

5 V 

6 public  function  messages() 

return  [ 

1 title . required ' =>  'A  title  is  required', 

1 body . required ' =>  'A  message  is  required', 


7 { 

8 
9 

10 

11 

12  } 


Working  With  Error  Messages 

After  calling  the  errors  method  on  a Val  idator  instance,  you  will  receive  an  1 1 luminate\Support\MessageBag 
instance,  which  has  a variety  of  convenient  methods  for  working  with  error  messages. 
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Retrieving  The  First  Error  Message  For  A Field 

To  retrieve  the  first  error  message  for  a given  field,  use  the  first  method: 


1 $messages  = $val idator- >errors( ) ; 

2 

3 echo  $messages- > f irst( ' emai 1 ' ) ; 


Retrieving  All  Error  Messages  For  A Field 

If  you  wish  to  simply  retrieve  an  array  of  all  of  the  messages  for  a given  field,  use  the  get  method: 


1 foreach  ($messages->get( 'email ' ) as  $message)  { 

2 // 

3 } 


Retrieving  All  Error  Messages  For  All  Fields 

To  retrieve  an  array  of  all  messages  for  all  fields,  use  the  all  method: 

1 foreach  ($messages->all( ) as  $message)  { 

2 // 

3 } 


Determining  If  Messages  Exist  For  A Field 


1 if  ($messages- >has( 1 emai 1 ' ) ) { 

2 // 

3 } 


Retrieving  An  Error  Message  With  A Format 
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1  echo  $messages- > f irst( ' emai 1 ' , ' <p> : message</p> ' ) ; 


Retrieving  All  Error  Messages  With  A Format 


1 foreach  ($messages->all( ' <li> :message</li> ' ) as  $message)  { 

2 // 

3 } 


Custom  Error  Messages 

If  needed,  you  may  use  custom  error  messages  for  validation  instead  of  the  defaults.  There  are  several 
ways  to  specify  custom  messages.  First,  you  may  pass  the  custom  messages  as  the  third  argument 
to  the  Validator : : make  method: 


1 Smessages  = [ 

'required'  =>  'The  :attribute  field  is  required.', 

3 ]; 

4 

5 Svalidator  = Validator: :make($input,  $rules,  Smessages); 


In  this  example,  the  : attribute  place-holder  will  be  replaced  by  the  actual  name  of  the  field  under 
validation.  You  may  also  utilize  other  place-holders  in  validation  messages.  For  example: 


1 

2 

Smessages  = [ 
' same ' 

=>  'The 

: attribute 

and  : 

: other  must 

match . ' , 

3 

' size ' 

=>  'The 

: attribute 

must 

be  exactly 

: size . ' , 

4 

' between ' 

=>  'The 

: attribute 

must 

be  between 

: min  - : max . ' , 

5 

6 

' in ' 

1; 

=>  'The 

: attribute 

must 

be  one  of  ■ 

the  following  types: 

: values 

Specifying  A Custom  Message  For  A Given  Attribute 

Sometimes  you  may  wish  to  specify  a custom  error  messages  only  for  a specific  field.  You  may  do 
so  using  “dot”  notation.  Specify  the  attribute’s  name  first,  followed  by  the  rule: 
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1 $messages  = [ 

' emai  1 . required ' =>  'We  need  to  know  your  e-mail  address! 

3 ]; 


Specifying  Custom  Messages  In  Language  Files 

In  many  cases,  you  may  wish  to  specify  your  attribute  specific  custom  messages  in  a language  file 
instead  of  passing  them  directly  to  the  Validator.  To  do  so,  add  your  messages  to  custom  array  in 
the  resources/lang/xx/val  idation  . php  language  file. 


'custom'  =>  [ 

' emai 1 ' =>  [ 

'required'  =>  'We  need  to  know  your  e-mail  address!', 


1 

2 

3 

4 

5 


Available  Validation  Rules 

Below  is  a list  of  all  available  validation  rules  and  their  function: 

<style>  A>  .collection-method-list  > p { A>  column-count:  3;  -moz-column-count:  3;  -webkit- 
column-count:  3;  A>  column-gap:  2em;  -moz-column-gap:  2em;  -webkit-column-gap:  2em;  A>  } A> 
A>  .collection- method-list  a { A>  display:  block;  A>  } 

</style> 

<div  class=”collection-method-list”  markdown=”  l”>  Accepted  Active  URL  After  (Date)  Alpha  Alpha 
Dash  Alpha  Numeric  Array  Before  (Date)  Between  Boolean  Confirmed  Date  Date  Format  Different 
Digits  Digits  Between  E-Mail  Exists  (Database)  Image  (File)  In  Integer  IP  Address  JSON  Max  MIME 
Types  (File)  Min  Not  In  Numeric  Regular  Expression  Required  Required  If  Required  Unless  Required 
With  Required  With  All  Required  Without  Required  Without  All  Same  Size  String  Timezone  Unique 
(Database)  URL  </div> 


accepted 

The  field  under  validation  must  be  yes,  on,  1,  or  true.  This  is  useful  for  validating  “Terms  of  Service’ 
acceptance. 
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active_url 

The  field  under  validation  must  be  a valid  URL  according  to  the  checkdnsrr  PHP  function. 

after  :date 

The  field  under  validation  must  be  a value  after  a given  date.  The  dates  will  be  passed  into  the 
strtotime  PHP  function: 

1 ' start_date ' =>  ' required  I date  I after : tomorrow ' 


Instead  of  passing  a date  string  to  be  evaluated  by  strtotime,  you  may  specify  another  field  to 
compare  against  the  date: 

1 ' f inish_date ' =>  ' required | date  I after : start_date ' 


alpha 

The  field  under  validation  must  be  entirely  alphabetic  characters. 

alpha_dash 

The  field  under  validation  may  have  alpha-numeric  characters,  as  well  as  dashes  and  underscores. 

alpha_num 

The  field  under  validation  must  be  entirely  alpha-numeric  characters. 

array 

The  field  under  validation  must  be  a PHP  array. 

befor e:date 


The  field  under  validation  must  be  a value  preceding  the  given  date.  The  dates  will  be  passed  into 
the  PHP  strtotime  function. 
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betvjeen:min,max 

The  field  under  validation  must  have  a size  between  the  given  min  and  max.  Strings,  numerics,  and 
files  are  evaluated  in  the  same  fashion  as  the  s i ze  rule. 

boolean 

The  field  under  validation  must  be  able  to  be  cast  as  a boolean.  Accepted  input  are  true,  false,  1, 
0,  "1",  and  "0". 

confirmed 

The  field  under  validation  must  have  a matching  field  of  foo_conf  irmation.  For  example,  if  the 
field  under  validation  is  password,  a matching  password_conf irmation  field  must  be  present  in  the 
input. 

date 

The  field  under  validation  must  be  a valid  date  according  to  the  strtotime  PHP  function. 

date_format:/ormot 

The  field  under  validation  must  match  the  given  format.  The  format  will  be  evaluated  using  the  PHP 
date_parse_from_format  function.  You  should  use  either  date  or  date_format  when  validating  a 
field,  not  both. 

different://e/d 

The  field  under  validation  must  have  a different  value  than  field. 

digitsivalue 

The  field  under  validation  must  be  numeric  and  must  have  an  exact  length  of  value. 

digits_between:m/nfmox 

The  field  under  validation  must  have  a length  between  the  given  min  and  max. 

email 


The  field  under  validation  must  be  formatted  as  an  e-mail  address. 
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exists:table,column 

The  field  under  validation  must  exist  on  a given  database  table. 

Basic  Usage  Of  Exists  Rule 


1 

'state'  => 

' exists : states ' 

Specifying  A Custom  Column  Name 

1 

'state'  => 

' exists : states , abbreviation ' 

You  may  also  specify  more  conditions  that  will  be  added  as  “where”  clauses  to  the  query: 

l 

' emai 1 ' => 

' exists : staff, emai 1 , account_id, 1 ' 

These  conditions 

may  be  negated  using  the  ! sign: 

l 

' emai 1 ' => 

' exists : staff, emai 1 , role, ! admin ' 

You  may  also  pass  NULL  or  NOT_NULL  to  the  “where”  clause: 

l 

' emai 1 ' => 

' exists : staff, emai 1 , deleted_at, NULL ' 

2 

3 

' emai 1 ' => 

' exists : staff, emai 1 , deleted_at, NOT_NULL ' 

image 

The  file  under  validation  must  be  an  image  (jpeg,  png,  bmp,  gif,  or  svg) 

in  :foo,bar,... 

The  field  under  validation  must  be  included  in  the  given  list  of  values. 
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integer 

The  field  under  validation  must  be  an  integer. 

'P 

The  field  under  validation  must  be  an  IP  address. 

json 

The  field  under  validation  must  a valid  JSON  string. 

ma  xivalue 

The  field  under  validation  must  be  less  than  or  equal  to  a maximum  value.  Strings,  numerics,  and 
files  are  evaluated  in  the  same  fashion  as  the  s i ze  rule. 

mimes:/oo,6arf... 

The  file  under  validation  must  have  a MIME  type  corresponding  to  one  of  the  listed  extensions. 


Basic  Usage  Of  MIME  Rule 

1 'photo'  =>  ' mimes : jpeg, bmp, png ' 


Even  though  you  only  need  to  specify  the  extensions,  this  rule  actually  validates  against  the  MIME 
type  of  the  file  by  reading  the  file’s  contents  and  guessing  its  MIME  type. 

A full  listing  of  MIME  types  and  their  corresponding  extensions  may  be  found  at  the  following 
location:  http://svn.apache.org/repos/asf/httpd/httpd/trunk/docs/conf/mime.types195 

minivalue 

The  field  under  validation  must  have  a minimum  value.  Strings,  numerics,  and  files  are  evaluated 
in  the  same  fashion  as  the  size  rule. 


not  _in:foo, bar,... 

The  field  under  validation  must  not  be  included  in  the  given  list  of  values. 

195http://svn.apache.org/repos/asf/httpd/httpd/trunk/docs/conf/mime.types 
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numeric 

The  field  under  validation  must  be  numeric. 

regex:pattern 

The  field  under  validation  must  match  the  given  regular  expression. 

Note:  When  using  the  regex  pattern,  it  may  be  necessary  to  specify  rules  in  an  array  instead  of 
using  pipe  delimiters,  especially  if  the  regular  expression  contains  a pipe  character. 

required 

The  field  under  validation  must  be  present  in  the  input  data  and  not  empty.  A field  is  considered 
“empty”  if  one  of  the  following  conditions  are  true: 

• The  value  is  null. 

• The  value  is  an  empty  string. 

• The  value  is  an  empty  array  or  empty  Countable  object. 

• The  value  is  an  uploaded  file  with  no  path. 

requiredjf ‘.anotherfield, value,... 

The  field  under  validation  must  be  present  if  the  anotherfield  field  is  equal  to  any  value. 

req  u i red_u  n\ess:anotherfield,  value,... 

The  field  under  validation  must  be  present  unless  the  anotherfield  field  is  equal  to  any  value. 

required  j/vith:/oo,6arf... 

The  field  under  validation  must  be  present  only  if  any  of  the  other  specified  fields  are  present. 

required_with_all  :foo,bar,... 

The  field  under  validation  must  be  present  only  if  all  of  the  other  specified  fields  are  present. 

required_without  :foo,bar,... 

The  field  under  validation  must  be  present  only  when  any  of  the  other  specified  fields  are  not  present. 

required_without_all  :foo,bar,... 

The  field  under  validation  must  be  present  only  when  all  of  the  other  specified  fields  are  not  present. 
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sam  e:field 

The  given  field  must  match  the  field  under  validation. 

sizeivalue 

The  field  under  validation  must  have  a size  matching  the  given  value.  For  string  data,  value 
corresponds  to  the  number  of  characters.  For  numeric  data,  value  corresponds  to  a given  integer 
value.  For  files,  size  corresponds  to  the  file  size  in  kilobytes. 

string 

The  field  under  validation  must  be  a string. 

timezone 

The  field  under  validation  must  be  a valid  timezone  identifier  according  to  the  timezone_identi - 
fiers_list  PHP  function. 


unique:  table,  column, excep  t.idColumn 

The  field  under  validation  must  be  unique  on  a given  database  table.  If  the  column  option  is  not 
specified,  the  field  name  will  be  used. 

Specifying  A Custom  Column  Name: 

1 'email'  =>  ' unique : users, emai l_address ' 


Custom  Database  Connection 

Occasionally,  you  may  need  to  set  a custom  connection  for  database  queries  made  by  the  Validator. 
As  seen  above,  setting  unique : users  as  a validation  rule  will  use  the  default  database  connection  to 
query  the  database.  To  override  this,  specify  the  connection  followed  by  the  table  name  using  “dot” 
syntax: 

1 'email'  =>  ' unique : connection . users, emai l_address ' 


Forcing  A Unique  Rule  To  Ignore  A Given  ID: 

Sometimes,  you  may  wish  to  ignore  a given  ID  during  the  unique  check.  For  example,  consider  an 
“update  profile”  screen  that  includes  the  user’s  name,  e-mail  address,  and  location.  Of  course,  you 
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will  want  to  verify  that  the  e-mail  address  is  unique.  However,  if  the  user  only  changes  the  name 
field  and  not  the  e-mail  field,  you  do  not  want  a validation  error  to  be  thrown  because  the  user 
is  already  the  owner  of  the  e-mail  address.  You  only  want  to  throw  a validation  error  if  the  user 
provides  an  e-mail  address  that  is  already  used  by  a different  user.  To  tell  the  unique  rule  to  ignore 
the  user’s  ID,  you  may  pass  the  ID  as  the  third  parameter: 

1 'email'  =>  ' unique : users, emai l_address, '. $user- > id 


If  your  table  uses  a primary  key  column  name  other  than  id,  you  may  specify  it  as  the  fourth 
parameter: 


1 'email'  =>  ' unique : users, emai l_address, '. $user- > id user_id ' 


Adding  Additional  Where  Clauses: 

You  may  also  specify  more  conditions  that  will  be  added  as  “where”  clauses  to  the  query: 
1 'email'  =>  ' unique : users, emai l_address, NULL, id, account_id, i ' 


In  the  rule  above,  only  rows  with  an  account_id  of  1 would  be  included  in  the  unique  check. 

url 

The  field  under  validation  must  be  a valid  URL  according  to  PHP’s  f i lter_var  function. 

Conditionally  Adding  Rules 

In  some  situations,  you  may  wish  to  run  validation  checks  against  a field  only  if  that  field  is  present 
in  the  input  array.  To  quickly  accomplish  this,  add  the  sometimes  rule  to  your  rule  list: 

1 $v  = Validator : :make($data,  [ 

'email'  =>  ' sometimes | required  I emai 1 ' , 

3 ]); 


In  the  example  above,  the  email  field  will  only  be  validated  if  it  is  present  in  the  $data  array. 
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Complex  Conditional  Validation 

Sometimes  you  may  wish  to  add  validation  rules  based  on  more  complex  conditional  logic.  For 
example,  you  may  wish  to  require  a given  field  only  if  another  field  has  a greater  value  than  100. 
Or,  you  may  need  two  fields  to  have  a given  value  only  when  another  field  is  present.  Adding  these 
validation  rules  doesn’t  have  to  be  a pain.  First,  create  a Validator  instance  with  your  static  rules 
that  never  change: 

1  $v  = Validator : :make($data,  [ 

'email'  =>  ' required  I emai 1 ' , 

'games'  =>  ' required  I numeric ' , 

4 ]); 


Let’s  assume  our  web  application  is  for  game  collectors.  If  a game  collector  registers  with  our 
application  and  they  own  more  than  100  games,  we  want  them  to  explain  why  they  own  so  many 
games.  For  example,  perhaps  they  run  a game  re-sell  shop,  or  maybe  they  just  enjoy  collecting.  To 
conditionally  add  this  requirement,  we  can  use  the  sometimes  method  on  the  Validator  instance. 


1 $v- >sometimes( ' reason ' , ' required  I max : 500 ' , function($input)  { 

return  $input- >games  >=  100; 

3 }); 


The  first  argument  passed  to  the  sometimes  method  is  the  name  of  the  field  we  are  conditionally 
validating.  The  second  argument  is  the  rules  we  want  to  add.  If  the  Closure  passed  as  the  third 
argument  returns  true,  the  rules  will  be  added.  This  method  makes  it  a breeze  to  build  complex 
conditional  validations.  You  may  even  add  conditional  validations  for  several  fields  at  once: 


1 $v- >sometimes( [' reason ' , 'cost'],  'required',  function($input)  { 

2 return  $input- >games  >=  100; 

3 }); 


Note:  The  $input  parameter  passed  to  your  Closure  will  be  an  instance  of 
Illuminate\Support\Fluent  and  may  be  used  to  access  your  input  and  files. 
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Custom  Validation  Rules 

Laravel  provides  a variety  of  helpful  validation  rules;  however,  you  may  wish  to  specify  some  of 
your  own.  One  method  of  registering  custom  validation  rules  is  using  the  extend  method  on  the 
Validator  facade.  Let’s  use  this  method  within  a service  provider  to  register  a custom  validation 
rule: 


1 < ?php 

2 

3 namespace  App\Providers; 

4 

5 use  Validator; 

6 use  1 1 luminate\Support\ServiceProvider ; 

7 

8 class  AppServiceProvider  extends  ServiceProvider 

9 { 

10  /** 

11  * Bootstrap  any  application  services. 

12  * 

13  * §return  void 

14  */ 

15  public  function  boot() 

16  { 

Validator  : extend( ' foo 1 , function(|attribute,  lvalue,  Iparameters,  $vali\ 

18  dator)  { 

19  return  lvalue  ==  'foo'; 

20  }); 

21  } 

22 

23  /** 

24  * Register  the  service  provider. 

25  * 

26  * §return  void 

27  */ 

28  public  function  register() 

29  { 

30  // 

31  } 

32  } 


The  custom  validator  Closure  receives  four  arguments:  the  name  of  the  Sattribute  being  validated, 
the  lvalue  of  the  attribute,  an  array  of  Iparameters  passed  to  the  rule,  and  the  Validator  instance. 
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You  may  also  pass  a class  and  method  to  the  extend  method  instead  of  a Closure: 


1 Validator: : extend (' foo' , ' FooVal idator@val idate ' ) ; 


Defining  The  Error  Message 

You  will  also  need  to  define  an  error  message  for  your  custom  rule.  You  can  do  so  either  using 
an  inline  custom  message  array  or  by  adding  an  entry  in  the  validation  language  file.  This  message 
should  be  placed  in  the  first  level  of  the  array,  not  within  the  custom  array,  which  is  only  for  attribute- 
specific  error  messages: 

1 "foo"  =>  "Your  input  was  invalid!", 

2 

3 "accepted"  =>  "The  attribute  must  be  accepted.", 

4 

5 //  The  rest  of  the  validation  error  messages... 


When  creating  a custom  validation  rule,  you  may  sometimes  need  to  define  custom  place-holder 
replacements  for  error  messages.  You  may  do  so  by  creating  a custom  Validator  as  described  above 
then  making  a call  to  the  replacer  method  on  the  Validator  facade.  You  may  do  this  within  the 
boot  method  of  a service  provider: 


1 /** 

2 * Bootstrap  any  application  services . 

3 * 

4 * §return  void 

5 V 

6 public  function  boot() 

7 { 

Val idator : : extend( . . . ) ; 

9 

Validator  replacer( ' foo ' , function($message,  $attribute,  $rule,  $parameters\ 

11  ) { 

12  return  str_replace(  . . . ) ; 

13  }); 

14  } 


Validation 


477 


Implicit  Extensions 

By  default,  when  an  attribute  being  validated  is  not  present  or  contains  an  empty  value  as  defined  by 
the  required  rule,  normal  validation  rules,  including  custom  extensions,  are  not  run.  For  example, 
the  unique  rule  will  not  be  run  against  a nul  1 value: 


1 Irules  = /"'name'  =>  'unique'7; 

2 

3 linput  = /"'name'  =>  nullj; 

4 

5 Validator: : make($input,  $rules)->passes( );  //  true 


For  a rule  to  run  even  when  an  attribute  is  empty,  the  rule  must  imply  that  the  attribute  is  required. 
To  create  such  an  “implicit”  extension,  use  the  Validator : : extend Impl icit( ) method: 

1 Validator : : extendlmpl icit( ' foo' , function($attr ibute,  lvalue,  Iparameters,  $vali\ 

2 dator)  { 

return  lvalue  ==  'foo'; 

4 }); 


Note:  An  “implicit”  extension  only  implies  that  the  attribute  is  required.  Whether  it  actually 
invalidates  a missing  or  empty  attribute  is  up  to  you. 
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Introduction 

Laravel  makes  connecting  with  databases  and  running  queries  extremely  simple  across  a variety 
of  database  back-ends  using  either  raw  SQL,  the  fluent  query  builder,  and  the  Eloquent  ORM. 
Currently,  Laravel  supports  four  database  systems: 

• MySQL 

• Postgres 

• SQLite 

• SQL  Server 

Configuration 

Laravel  makes  connecting  with  databases  and  running  queries  extremely  simple.  The  database 
configuration  for  your  application  is  located  at  conf  ig/database . php.  In  this  file  you  may  define 
all  of  your  database  connections,  as  well  as  specify  which  connection  should  be  used  by  default. 
Examples  for  all  of  the  supported  database  systems  are  provided  in  this  file. 

By  default,  Laravel’s  sample  environment  configuration  is  ready  to  use  with  Laravel  Homestead, 
which  is  a convenient  virtual  machine  for  doing  Laravel  development  on  your  local  machine.  Of 
course,  you  are  free  to  modify  this  configuration  as  needed  for  your  local  database. 

Read  / Write  Connections 

Sometimes  you  may  wish  to  use  one  database  connection  for  SELECT  statements,  and  another  for 
INSERT,  UPDATE,  and  DELETE  statements.  Laravel  makes  this  a breeze,  and  the  proper  connections 
will  always  be  used  whether  you  are  using  raw  queries,  the  query  builder,  or  the  Eloquent  ORM. 

To  see  how  read  / write  connections  should  be  configured,  let’s  look  at  this  example: 


478 


Database:  Getting  Started 


479 


1 

' mysql ' =>  [ 

2 

'read'  => 

3 

1 host ' 

=> 

192.168.1.1', 

4 

], 

5 

'write'  => 

[ 

6 

' host ' 

=> 

196.168.1.2’ 

7 

], 

8 

' driver ' 

=> 

' mysql 1 , 

9 

' database ' 

=> 

' database ' , 

10 

' username ' 

=> 

' root ' , 

11 

' password ' 

=> 

/ 

12 

' charset ' 

=> 

' utf8 ' , 

13 

' col lation 

=> 

' utf8_unicode_ci 1 , 

14 

' prefix' 

=> 

/ 

15 

], 

Note  that  two  keys  have  been  added  to  the  configuration  array:  read  and  write.  Both  of  these  keys 
have  array  values  containing  a single  key:  host.  The  rest  of  the  database  options  for  the  read  and 
write  connections  will  be  merged  from  the  main  mysql  array. 

So,  we  only  need  to  place  items  in  the  read  and  write  arrays  if  we  wish  to  override  the  values  in  the 
main  array.  So,  in  this  case,  192.168.1.1  will  be  used  as  the  “read”  connection,  while  192 . 168 . 1 . 2 
will  be  used  as  the  “write”  connection.  The  database  credentials,  prefix,  character  set,  and  all  other 
options  in  the  main  mysql  array  will  be  shared  across  both  connections. 

Running  Raw  SQL  Queries 

Once  you  have  configured  your  database  connection,  you  may  run  queries  using  the  DB  facade.  The 
DB  facade  provides  methods  for  each  type  of  query:  select,  update,  insert,  delete,  and  statement. 


Running  A Select  Query 

To  run  a basic  query,  we  can  use  the  select  method  on  the  DB  facade: 
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1 < ?php 

2 

3 namespace  App\Http\Control lers; 

4 

5 use  DB; 

6 use  App\Http\Controllers\Controller; 

7 

8 class  UserController  extends  Controller 

9 { 

10  /** 

11  * Show  a list  of  all  of  the  application's  users. 

12  * 

13  * §return  Response 

14  */ 

15  public  function  index() 

16  { 

17  $users  = DB  : select( ' select  * from  users  where  active  = ?',  [1]); 

18 

19  return  view( 1 user . index ' , ['users'  =>  $users]); 

20  } 

21  } 


The  first  argument  passed  to  the  select  method  is  the  raw  SQL  query,  while  the  second  argument 
is  any  parameter  bindings  that  need  to  be  bound  to  the  query  Typically,  these  are  the  values  of  the 
where  clause  constraints.  Parameter  binding  provides  protection  against  SQL  injection. 

The  select  method  will  always  return  an  array  of  results.  Each  result  within  the  array  will  be  a 
PHP  StdClass  object,  allowing  you  to  access  the  values  of  the  results: 

1 foreach  ($users  as  $user)  { 
echo  $user->name; 

3 } 


Using  Named  Bindings 

Instead  of  using  ? to  represent  your  parameter  bindings,  you  may  execute  a query  using  named 
bindings: 
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1 $results  = DB :: select( ' select  * from  users  where  id  = : i d ' , ['id'  =>  lj); 

Running  An  Insert  Statement 

To  execute  an  insert  statement,  you  may  use  the  insert  method  on  the  DB  facade.  Like  select,  this 
method  takes  the  raw  SQL  query  as  its  first  argument,  and  bindings  as  the  second  argument: 

1 DB:  : insert( ' insert  into  users  (id,  name)  values  (?,  ?)',  [i , ’Dayle'J); 


Running  An  Update  Statement 

The  update  method  should  be  used  to  update  existing  records  in  the  database.  The  number  of  rows 
affected  by  the  statement  will  be  returned  by  the  method: 

1 $affected  = DB :: update( ' update  users  set  votes  = 100  where  name  = ?',  [’ John' ]); 


Running  A Delete  Statement 

The  delete  method  should  be  used  to  delete  records  from  the  database.  Like  update,  the  number  of 
rows  deleted  will  be  returned: 

1 $deleted  = DB :: delete( 1 delete  from  users’); 


Running  A General  Statement 

Some  database  statements  should  not  return  any  value.  For  these  types  of  operations,  you  may  use 
the  statement  method  on  the  DB  facade: 

1 DB : : statement( ' drop  table  users'); 
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Listening  For  Query  Events 

If  you  would  like  to  receive  each  SQL  query  executed  by  your  application,  you  may  use  the  listen 
method.  This  method  is  useful  for  logging  queries  or  debugging.  You  may  register  your  query  listener 
in  a service  provider: 

1 < ?php 

2 

3 namespace  App\Providers; 

4 

5 use  DB; 

6 use  Illuminate\Support\ServiceProvider; 

7 

8 class  AppServiceProvider  extends  ServiceProvider 

9 { 

10  /** 

11  * Bootstrap  any  application  services. 

12  * 

13  * § return  void 

14  */ 

15  public  function  boot() 

16  { 

17  DB  : 1 isten( function($query)  { 

18  //  $query->sql 

19  //  $query-> bindings 

20  //  $query->time 

21  }); 

22  } 

23 

24  /** 

25  * Register  the  service  provider. 

26  * 

27  * §return  void 

28  */ 

29  public  function  register!) 

30  { 

31  // 

32  } 

33 


} 
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Database  Transactions 

To  run  a set  of  operations  within  a database  transaction,  you  may  use  the  transaction  method 
on  the  DB  facade.  If  an  exception  is  thrown  within  the  transaction  Closure,  the  transaction  will 
automatically  be  rolled  back.  If  the  Closure  executes  successfully,  the  transaction  will  automatically 
be  committed.  You  don’t  need  to  worry  about  manually  rolling  back  or  committing  while  using  the 
transaction  method: 


1 DB :: transaction( function  ()  { 

DB  :table( 'users' )->update(/"' votes'  =>  lj); 

3 

DB  : table( ' posts ')- >delete( ) ; 

5 }); 


Manually  Using  Transactions 

If  you  would  like  to  begin  a transaction  manually  and  have  complete  control  over  rollbacks  and 
commits,  you  may  use  the  beginTransaction  method  on  the  DB  facade: 

1 DB : : beginTransaction( ) ; 

You  can  rollback  the  transaction  via  the  rol  IBack  method: 

1 DB : : rol lBack( ) ; 

Lastly,  you  can  commit  a transaction  via  the  commit  method: 

1 DB:  : commit( ) ; 


Note:  Using  the  DB  facade’s  transaction  methods  also  controls  transactions  for  the  query 
builder  and  Eloquent  ORM. 
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Using  Multiple  Database  Connections 

When  using  multiple  connections,  you  may  access  each  connection  via  the  connection  method 
on  the  DB  facade.  The  name  passed  to  the  connection  method  should  correspond  to  one  of  the 
connections  listed  in  your  conf  ig/database . php  configuration  file: 


1 $users  = DB: :connection( ' foo' )->select( . . . ); 


You  may  also  access  the  raw,  underlying  PDO  instance  using  the  getPdo  method  on  a connection 
instance: 

1 $pdo  = DB : : connection( ) - >getPdo( ) ; 
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Introduction 


The  database  query  builder  provides  a convenient,  fluent  interface  to  creating  and  running  database 
queries.  It  can  be  used  to  perform  most  database  operations  in  your  application,  and  works  on  all 
supported  database  systems. 


Note:  The  Laravel  query  builder  uses  PDO  parameter  binding  to  protect  your  application 
against  SQL  injection  attacks.  There  is  no  need  to  clean  strings  being  passed  as  bindings. 


Retrieving  Results 

Retrieving  All  Rows  From  A Table 

To  begin  a fluent  query,  use  the  table  method  on  the  DB  facade.  The  table  method  returns  a fluent 
query  builder  instance  for  the  given  table,  allowing  you  to  chain  more  constraints  onto  the  query 
and  then  finally  get  the  results.  In  this  example,  let’s  just  get  all  records  from  a table: 
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1 < ?php 

2 

3 namespace  App\Http\Control lers; 

4 

5 use  DB; 

6 use  App\Http\Controllers\Controller; 

7 

8 class  UserController  extends  Controller 

9 { 

10  /** 

11  * Show  a list  of  all  of  the  application's  users. 

12  * 

13  * §return  Response 

14  V 

15  public  function  index() 

16  { 

$users  = DB  : table( ' users ')- >get( ) ; 

18 

return  view( 1 2 user . index ' , ['users'  =>  $users]); 

20  } 

21  } 


Like  raw  queries,  the  get  method  returns  an  array  of  results  where  each  result  is  an  instance  of  the 
PHP  StdClass  object.  You  may  access  each  column’s  value  by  accessing  the  column  as  a property 
of  the  object: 

1 foreach  ($users  as  $user)  { 
echo  $user->name; 

3 } 


Retrieving  A Single  Row  / Column  From  A Table 

If  you  just  need  to  retrieve  a single  row  from  the  database  table,  you  may  use  the  first  method. 
This  method  will  return  a single  StdClass  object: 


1 $user  = DB :: table( ' users ') ->where( ’ name ' , ' John ' ) - > f irst( ) ; 

2 
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3 echo  $user->name; 


If  you  don’t  even  need  an  entire  row,  you  may  extract  a single  value  from  a record  using  the  value 
method.  This  method  will  return  the  value  of  the  column  directly: 

1 Semail  = DB :: table( ' users ')- >where( ' name ' , 'John' )->value( 'email ' ); 


Chunking  Results  From  A Table 

If  you  need  to  work  with  thousands  of  database  records,  consider  using  the  chunk  method.  This 
method  retrieves  a small  “chunk”  of  the  results  at  a time,  and  feeds  each  chunk  into  a Closure  for 
processing.  This  method  is  very  useful  for  writing  Artisan  commands  that  process  thousands  of 
records.  For  example,  let’s  work  with  the  entire  users  table  in  chunks  of  100  records  at  a time: 


1 DB :: table( ' users ') ->chunk(100,  function($users)  { 
foreach  ($users  as  $user)  { 

3 // 

4 } 

5 }); 


You  may  stop  further  chunks  from  being  processed  by  returning  false  from  the  Closure: 


1 DB :: table( ' users ') ->chunk(100,  function($users)  { 
//  Process  the  records . . . 

3 

4 return  false; 

5 }); 


Retrieving  A List  Of  Column  Values 

If  you  would  like  to  retrieve  an  array  containing  the  values  of  a single  column,  you  may  use  the 
pluck  method.  In  this  example,  we’ll  retrieve  an  array  of  role  titles: 
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1 Stitles  = DB: :table( 'roles' )->pluck( 'title' ); 

2 

3 foreach  (Stitles  as  Stitle)  { 

4 echo  Stitle; 

5 } 


You  may  also  specify  a custom  key  column  for  the  returned  array: 

1 Sroles  = DB: :table( 'roles' )->pluck( 'title' , 'name'); 

2 

3 foreach  (Sroles  as  Sname  =>  Stitle)  { 

4 echo  Stitle; 

5 } 


Aggregates 

The  query  builder  also  provides  a variety  of  aggregate  methods,  such  as  count,  max,  min,  avg,  and 
sum.  You  may  call  any  of  these  methods  after  constructing  your  query: 

1 Susers  = DB :: table( ' users ')- >count( ) ; 

2 

3 Sprice  = DB :: table( ' orders ')- >max( ' price ') ; 


Of  course,  you  may  combine  these  methods  with  other  clauses  to  build  your  query: 


1 Sprice  = DB :: table( ' orders ' ) 

->where( ' final ized ' , 1) 
->avg( 'price ' ) ; 
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Selects 

Specifying  A Select  Clause 

Of  course,  you  may  not  always  want  to  select  all  columns  from  a database  table.  Using  the  select 
method,  you  can  specify  a custom  select  clause  for  the  query: 

1 $users  = DB :: table( ' users ')- >select( ' name ' , 'email  as  user_emai 1 ' ) - >get( ) ; 

The  distinct  method  allows  you  to  force  the  query  to  return  distinct  results: 

1 $users  = DB :: table( ' users ')- >distinct( )- >get( ) ; 


If  you  already  have  a query  builder  instance  and  you  wish  to  add  a column  to  its  existing  select 
clause,  you  may  use  the  addSelect  method: 

1 $query  = DB :: table( ' users ')- >select( ' name ') ; 

2 

3 $users  = $query->addSelect( 'age' )->get( ); 


Raw  Expressions 

Sometimes  you  may  need  to  use  a raw  expression  in  a query.  These  expressions  will  be  injected  into 
the  query  as  strings,  so  be  careful  not  to  create  any  SQL  injection  points!  To  create  a raw  expression, 
you  may  use  the  DB : : raw  method: 


1 

2 

3 

4 

5 


$users  = DB :: table( 1 users ' ) 

->select(DB: :raw( 'count(*)  as  user_count,  status')) 
- >where( ' status ' , ’<>',  1) 

->groupBy( 'status'  ) 

- >get( ) ; 
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Joins 

Inner  Join  Statement 

The  query  builder  may  also  be  used  to  write  join  statements.  To  perform  a basic  SQL  “inner  join”, 
you  may  use  the  join  method  on  a query  builder  instance.  The  first  argument  passed  to  the  join 
method  is  the  name  of  the  table  you  need  to  join  to,  while  the  remaining  arguments  specify  the 
column  constraints  for  the  join.  Of  course,  as  you  can  see,  you  can  join  to  multiple  tables  in  a single 
query: 


1 $users  = DB :: table( ' users ' ) 

- >join( 1 contacts  1 , 'users. id',  ' = ’,  ' contacts . user_id ' ) 
- >join( ' orders ' , 'users. id',  '=',  ' orders . user_id ' ) 

- >select( ' users . *' , ' contacts . phone ' , ' orders . price ' ) 

5 - >get( ) ; 


Left  Join  Statement 


If  you  would  like  to  perform  a “left  join”  instead  of  an  “inner  join”,  use  the  left  Jo  in  method.  The 
left  Join  method  has  the  same  signature  as  the  join  method: 

1 $users  = DB :: table( ' users ' ) 

-> leftJoin( ' posts ' , 'users. id',  '=',  ' posts . user_id ' ) 

3 - >get( ) ; 


Advanced  Join  Statements 

You  may  also  specify  more  advanced  join  clauses.  To  get  started,  pass  a Closure  as  the  second 
argument  into  the  join  method.  The  Closure  will  receive  a JoinClause  object  which  allows  you  to 
specify  constraints  on  the  join  clause: 


1 DB :: table( ' users ' ) 

->join( 'contacts' , function  ($join)  { 

$join- >on( ' users . id ' , '=',  ' contacts . user_id ') ->orOn( ...) ; 

1) 
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->get(); 


If  you  would  like  to  use  a “where”  style  clause  on  your  joins,  you  may  use  the  where  and  orWhere 
methods  on  a join.  Instead  of  comparing  two  columns,  these  methods  will  compare  the  column 
against  a value: 

1 DB :: table( ' users ' ) 

->join( 'contacts' , function  ($join)  { 

$join- >on( ' users . id ' , '=',  ' contacts . user_id ' ) 

4 - >where( ' contacts . user_id ' , '>',  5); 

5 }) 

6 ->get( ) ; 


Unions 


The  query  builder  also  provides  a quick  way  to  “union”  two  queries  together.  For  example,  you  may 
create  an  initial  query,  and  then  use  the  union  method  to  union  it  with  a second  query: 


1 $first  = DB :: table( ' users ' ) 

- >whereNul 1 ( ' f irst_name ' ) ; 

3 

4 $users  = DB :: table( ' users ' ) 

5 - >whereNul 1 ( 1 last_name ' ) 

6 ->union($first) 

- >get( ) ; 


The  unionAll  method  is  also  available  and  has  the  same  method  signature  as  union. 


Where  Clauses 

Simple  Where  Clauses 

To  add  where  clauses  to  the  query,  use  the  where  method  on  a query  builder  instance.  The  most 
basic  call  to  where  requires  three  arguments.  The  first  argument  is  the  name  of  the  column.  The 
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second  argument  is  an  operator,  which  can  be  any  of  the  database’s  supported  operators.  The  third 
argument  is  the  value  to  evaluate  against  the  column. 

For  example,  here  is  a query  that  verifies  the  value  of  the  “votes”  column  is  equal  to  100: 


1 

Susers  = DB : 

table( ' users ')■ >where( ' votes ' , 100)->get(); 

For  convenience,  if  you  simply  want  to  verify  that  a column  is  equal  to  a given  value,  you  may  pass 
the  value  directly  as  the  second  argument  to  the  where  method: 

l 

Susers  = DB : 

table ( ' users ' ) - > where ( ' votes ' , 100) ->get( ) ; 

Of  course,  you  may  use  a variety  of  other  operators  when  writing  a where  clause: 

l 

Susers  = DB : 

table( ' users ' ) 

2 

- >where( ' votes ' , 100) 

3 

4 

- >get( ) ; 

5 

Susers  = DB : 

table( ' users ' ) 

6 

7 

8 
9 

- >where( ' votes ' , 100) 

- >get( ) ; 

Susers  = DB : 

table( 1 users ' ) 

10 

- >where( ' name ' , 'like',  ' T% ' ) 

11 

- >get( ) ; 

You 

may  also  pass  an  array  of  conditions  to  the  where  function: 

l 

Susers  = DB : 

table( ' users ' ) - >where( [ 

2 

[ ' status 

,'i'L 

3 

[ ' subscr i bed 1 ' ] , 

4 

1 )->get(); 
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Or  Statements 

You  may  chain  where  constraints  together,  as  well  as  add  or  clauses  to  the  query.  The  orWhere 
method  accepts  the  same  arguments  as  the  where  method: 


1 $users  = DB :: table(*  1 users ' ) 

- >where( ' votes ' , '>',  100) 
- >orWhere( 1 name ' , 'John') 

4 ->get(); 


Additional  Where  Clauses 

whereBetween 

The  whereBetween  method  verifies  that  a column’s  value  is  between  two  values: 

1 $users  = DB :: table( ' users ' ) 

- >whereBetween( ' votes ' , [1,  100] ) - >get( ) ; 


whereNotBetween 

The  whereNotBetween  method  verifies  that  a column’s  value  lies  outside  of  two  values: 


1 $users  = DB :: table( ' users ' ) 

-> whereNotBetween (’ votes  1 , [1,  100]) 
- >get( ) ; 


wherein  / whereNotln 

The  wherein  method  verifies  that  a given  column’s  value  is  contained  within  the  given  array: 


1 $users  = DB :: table( ' users ' ) 

- >whereln( 1 id  1 , [1,  2,  3]) 
->get(); 


The  whereNotln  method  verifies  that  the  given  column’s  value  is  not  contained  in  the  given  array: 
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1 $users  = DB :: table( 1 * * 4 5 6 users ' ) 

- >whereNotIn( ' id ' , [1,  2,  3]) 
->get( ); 


whereNull  / whereNotNull 

The  whereNull  method  verifies  that  the  value  of  the  given  column  is  NULL: 


1 $users  = DB :: table( 1 users ' ) 

- >whereNul 1 ( ' updated_at ' ) 
->get( ) ; 


The  whereNotNull  method  verifies  that  the  column’s  value  is  not  NULL: 


1 $users  = DB :: table( 1 users ' ) 

- >whereNotNul 1 ( ' updated_at ' ) 
->get(); 


Advanced  Where  Clauses 

Parameter  Grouping 

Sometimes  you  may  need  to  create  more  advanced  where  clauses  such  as  “where  exists”  or  nested 
parameter  groupings.  The  Laravel  query  builder  can  handle  these  as  well.  To  get  started,  let’s  look 
at  an  example  of  grouping  constraints  within  parenthesis: 


1 DB :: table( ' users ' ) 

- >where( ' name ' , 'John') 

- >orWhere( function  ($query)  { 

4 $query- >where( ' votes ' , ’>',  100) 

5 - >where( ' title ' , '<>',  'Admin'); 

6 }) 

- >get( ) ; 
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As  you  can  see,  passing  Closure  into  the  orWhere  method  instructs  the  query  builder  to  begin  a 
constraint  group.  The  Closure  will  receive  a query  builder  instance  which  you  can  use  to  set  the 
constraints  that  should  be  contained  within  the  parenthesis  group.  The  example  above  will  produce 
the  following  SQL: 


1 select  * from  users  where  name  = 'John'  or  (votes  > 100  and  title  <>  'Admin') 


Exists  Statements 

The  whereExists  method  allows  you  to  write  where  exist  SQL  clauses.  The  whereExists  method 
accepts  a Closure  argument,  which  will  receive  a query  builder  instance  allowing  you  to  define  the 
query  that  should  be  placed  inside  of  the  “exists”  clause: 


1 DB :: table( ' users ' ) 

- >whereExists( function  ($query)  { 
$query->select(DB: :raw(l)) 

4 -> from( ' orders ' ) 

5 - >whereRaw( ' orders . user_id  = users. id'); 

6 }) 

->get( ); 


The  query  above  will  produce  the  following  SQL: 


1 select  * from  users 

2 where  exists  ( 

select  1 from  orders  where  orders . user_id  = users. id 

4 ) 


Ordering,  Grouping,  Limit,  & Offset 

orderBy 

The  orderBy  method  allows  you  to  sort  the  result  of  the  query  by  a given  column.  The  first  argument 
to  the  orderBy  method  should  be  the  column  you  wish  to  sort  by,  while  the  second  argument  controls 
the  direction  of  the  sort  and  may  be  either  asc  or  desc: 
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1 

$users  = DB :: table( ' users ' ) 

2 

->orderBy( 'name' , 

' desc ' ) 

3 

- >get( ) ; 

groupBy  / having  / havingRaw 

The  groupBy  and  having  methods  may  be  used  to  group  the  query  results.  The  having  method’s 
signature  is  similar  to  that  of  the  where  method: 

1 $users  = DB :: table( ' users ' ) 

2 ->groupBy( 'account_id' ) 

- >having( ' account_id ' , 100) 

4 - >get( ) ; 


The  havingRaw  method  may  be  used  to  set  a raw  string  as  the  value  of  the  having  clause.  For  example, 
we  can  find  all  of  the  departments  with  sales  greater  than  $2,500: 


1 

2 

3 

4 

5 


$users  = DB :: table( 1 orders ' ) 

->select( 'department' , DB : : raw( ' SUM(price)  as  total_sales ' ) ) 
->groupBy( 'department' ) 

->havingRaw( ' SUM(price)  > 2500') 

->get( ) ; 


skip  / take 

To  limit  the  number  of  results  returned  from  the  query,  or  to  skip  a given  number  of  results  in  the 
query  (OFFSET),  you  may  use  the  skip  and  take  methods: 

1 $users  = DB: :table( 'users' )->skip(10)->take(5)->get( ); 
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Inserts 


The  query  builder  also  provides  an  insert  method  for  inserting  records  into  the  database  table.  The 
insert  method  accepts  an  array  of  column  names  and  values  to  insert: 

1 DB :: table( ' users ')-> insert( 

['email'  =>  'john@example.com',  'votes'  =>  0] 

3 ); 


You  may  even  insert  several  records  into  the  table  with  a single  call  to  insert  by  passing  an  array 
of  arrays.  Each  array  represents  a row  to  be  inserted  into  the  table: 


1 DB :: table( ' users ')-> insert( [ 

['email'  =>  'taylor@example.com',  'votes'  =>  0] , 
['email'  =>  'dayle@example.com',  'votes'  =>  0] 


Auto-Incrementing  IDs 

If  the  table  has  an  auto-incrementing  id,  use  the  insertGetld  method  to  insert  a record  and  then 
retrieve  the  ID: 


4 ]); 


1 $id  = DB  ::  table(  ' users ')->  insertGetId( 

['email'  =>  'john@example.com',  'votes'  =>  0] 

3 ); 


o 


Note:  When  using  PostgreSQL  the  insertGetld  method  expects  the  auto-incrementing 
column  to  be  named  id.  If  you  would  like  to  retrieve  the  ID  from  a different  “sequence”, 
you  may  pass  the  sequence  name  as  the  second  parameter  to  the  insertGetld  method. 


Updates 


Of  course,  in  addition  to  inserting  records  into  the  database,  the  query  builder  can  also  update 
existing  records  using  the  update  method.  The  update  method,  like  the  insert  method,  accepts 
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an  array  of  column  and  value  pairs  containing  the  columns  to  be  updated.  You  may  constrain  the 
update  query  using  where  clauses: 


1 DB :: table( ' users ' ) 

- >where( ' id ' , 1 ) 

->update( [ 'votes'  =>  1]); 


Increment  / Decrement 

The  query  builder  also  provides  convenient  methods  for  incrementing  or  decrementing  the  value  of 
a given  column.  This  is  simply  a short-cut,  providing  a more  expressive  and  terse  interface  compared 
to  manually  writing  the  update  statement. 

Both  of  these  methods  accept  at  least  one  argument:  the  column  to  modify.  A second  argument 
may  optionally  be  passed  to  control  the  amount  by  which  the  column  should  be  incremented  / 
decremented. 

1 DB : : tabl  e( ' users ' ) -> increment ( ' votes ' ) ; 

2 

3 DB :: table( ' users ')-> increment( ' votes ' , 5); 

4 

5 DB : : tabl  e( ' users ' ) - >decrement( ' votes ' ) ; 

6 

7 DB: :table( 'users' )->decrement( 'votes' , 5); 


You  may  also  specify  additional  columns  to  update  during  the  operation: 


1 DB :: table( ' users ')-> increment( ' votes ' , 1,  ['name'  =>  'John'J); 


Deletes 


Of  course,  the  query  builder  may  also  be  used  to  delete  records  from  the  table  via  the  delete  method: 
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1 DB : : tabl  e( ' users ' ) - > delete ( ) ; 


You  may  constrain  delete  statements  by  adding  where  clauses  before  calling  the  delete  method: 


1 DB : : tabl  e( ' users ')- >where( ' votes ' , 100) - >delete( ) ; 


If  you  wish  to  truncate  the  entire  table,  which  will  remove  all  rows  and  reset  the  auto-incrementing 
ID  to  zero,  you  may  use  the  truncate  method: 


1 DB : : tabl  e( ' users ' ) - >truncate( ) ; 


Pessimistic  Locking 


The  query  builder  also  includes  a few  functions  to  help  you  do  “pessimistic  locking”  on  your  select 
statements.  To  run  the  statement  with  a “shared  lock”,  you  may  use  the  sharedLock  method  on  a 
query.  A shared  lock  prevents  the  selected  rows  from  being  modified  until  your  transaction  commits: 

1 DB : : tabl  e( ' users ')- >where( ' votes ' , 100) - >sharedLock( ) - >get( ) ; 


Alternatively,  you  may  use  the  lockForUpdate  method.  A “for  update”  lock  prevents  the  rows  from 
being  modified  or  from  being  selected  with  another  shared  lock: 


1 DB : : tabl  e( ' users ')- >where( ' votes ' , 100) - > lockFortlpdate( )->get( ) ; 
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Introduction 

Migrations  are  like  version  control  for  your  database,  allowing  a team  to  easily  modify  and  share 
the  application’s  database  schema.  Migrations  are  typically  paired  with  Laravel’s  schema  builder  to 
easily  build  your  application’s  database  schema. 

The  Laravel  Schema  facade  provides  database  agnostic  support  for  creating  and  manipulating  tables. 
It  shares  the  same  expressive,  fluent  API  across  all  of  Laravel’s  supported  database  systems. 

Generating  Migrations 

To  create  a migration,  use  the  make: migration  Artisan  command: 


1 php  artisan  make : migration  create_users_table 


The  new  migration  will  be  placed  in  your  database/migrations  directory.  Each  migration  file  name 
contains  a timestamp  which  allows  Laravel  to  determine  the  order  of  the  migrations. 

The  - -table  and  - -create  options  may  also  be  used  to  indicate  the  name  of  the  table  and  whether 
the  migration  will  be  creating  a new  table.  These  options  simply  pre-fdl  the  generated  migration 
stub  file  with  the  specified  table: 
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1 php  artisan  make : migration  add_votes_to_users_table  - -table=users 

2 

3 php  artisan  make : migration  create_users_table  - -create=users 


If  you  would  like  to  specify  a custom  output  path  for  the  generated  migration,  you  may  use  the 
- - path  option  when  executing  the  make : migration  command.  The  provided  path  should  be  relative 
to  your  application’s  base  path. 

Migration  Structure 

A migration  class  contains  two  methods:  up  and  down.  The  up  method  is  used  to  add  new  tables, 
columns,  or  indexes  to  your  database,  while  the  down  method  should  simply  reverse  the  operations 
performed  by  the  up  method. 

Within  both  of  these  methods  you  may  use  the  Laravel  schema  builder  to  expressively  create  and 
modify  tables.  To  learn  about  all  of  the  methods  available  on  the  Schema  builder,  check  out  its 
documentation.  For  example,  let’s  look  at  a sample  migration  that  creates  a flights  table: 

1 < ?php 

2 

3 use  1 1 luminate\Database\Schema\Bluepr int; 

4 use  Illuminate\Database\Migrations\Migration; 

5 

6 class  CreateFlightsTable  extends  Migration 

7 { 

8 /** 

9 * Run  the  migrations . 

10  * 

11  * @return  void 

12  */ 

13  public  function  up() 

14  { 

15  Schema  : create! ' fl ights ' , function  (Blueprint  Stable)  { 

16  $table-> increments! 1 11 id ') ; 

17  $table->string( ' name ' ) ; 

18  $table->string( 'airline' ) ; 

19  Stable- >timestamps( ) ; 

20 

21  } 

22 

23  /** 


}); 
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24  * Reverse  the  migrations . 

25  * 

26  * §return  void 

27  */ 

public  function  down() 

29  { 

Schema : : drop( ' f 1 ights 1 ) ; 

31  } 

32  } 


Running  Migrations 

To  run  all  outstanding  migrations  for  your  application,  use  the  migrate  Artisan  command.  If  you 
are  using  the  Homestead  virtual  machine,  you  should  run  this  command  from  within  your  VM: 


1 php  artisan  migrate 


If  you  receive  a “class  not  found”  error  when  running  migrations,  try  running  the  composer  dump- 
autoload  command  and  re-issuing  the  migrate  command. 

Forcing  Migrations  To  Run  In  Production 

Some  migration  operations  are  destructive,  meaning  they  may  cause  you  to  lose  data.  In  order  to 
protect  you  from  running  these  commands  against  your  production  database,  you  will  be  prompted 
for  confirmation  before  these  commands  are  executed.  To  force  the  commands  to  run  without  a 
prompt,  use  the  - - force  flag: 


1 php  artisan  migrate  --force 


Rolling  Back  Migrations 

To  rollback  the  latest  migration  “operation”,  you  may  use  the  rollback  command.  Note  that  this 
rolls  back  the  last  “batch”  of  migrations  that  ran,  which  may  include  multiple  migration  files: 
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1  php  artisan  migrate : rol lback 


The  migrate : reset  command  will  roll  back  all  of  your  application’s  migrations: 
1 php  artisan  migrate : reset 


Rollback  / Migrate  In  Single  Command 

The  migrate:  refresh  command  will  first  roll  back  all  of  your  database  migrations,  and  then  run 
the  migrate  command.  This  command  effectively  re-creates  your  entire  database: 

1 php  artisan  migrate : refresh 

2 

3 php  artisan  migrate : refresh  --seed 


Writing  Migrations 

Creating  Tables 

To  create  a new  database  table,  use  the  create  method  on  the  Schema  facade.  The  create  method 
accepts  two  arguments.  The  first  is  the  name  of  the  table,  while  the  second  is  a Closure  which 
receives  a Blueprint  object  used  to  define  the  new  table: 


1 Schema :: create( ' users ' , function  (Blueprint  Stable)  { 

2 Stable- > increments( ' id ') ; 

3 }); 


Of  course,  when  creating  the  table,  you  may  use  any  of  the  schema  builder’s  column  methods  to 
define  the  table’s  columns. 

Checking  For  Table  / Column  Existence 

You  may  easily  check  for  the  existence  of  a table  or  column  using  the  hasTable  and  hasColumn 
methods: 
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1 if  (Schema :: hasTable( ' users ') ) { 

2 // 

3 } 

4 

5 if  (Schema :: hasColumn( ' users  1 , 'email'))  { 

6 // 

7 } 


Connection  & Storage  Engine 

If  you  want  to  perform  a schema  operation  on  a database  connection  that  is  not  your  default 
connection,  use  the  connection  method: 

1 Schema :: connection( ' foo ') ->create( ' users ' , function  ($table)  { 

Stable- > increments ( ' id ' ) ; 

3 }); 


To  set  the  storage  engine  for  a table,  set  the  engine  property  on  the  schema  builder: 


1 Schema :: create( ' users ' , function  (Stable)  { 
Stable- >engine  = 'InnoDB'; 

3 

Stable- > increments ( ' id ' ) ; 

5 }); 


Renaming  / Dropping  Tables 

To  rename  an  existing  database  table,  use  the  rename  method: 


1 Schema : :rename($from,  $to); 


To  drop  an  existing  table,  you  may  use  the  drop  or  drop  I f Exists  methods: 
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1 Schema :: drop( ' users ') ; 

2 

3 Schema :: dropl fExists( ' users ') ; 


Creating  Columns 

To  update  an  existing  table,  we  will  use  the  table  method  on  the  Schema  facade.  Like  the  create 
method,  the  table  method  accepts  two  arguments:  the  name  of  the  table  and  a Closure  that  receives 
a Blueprint  instance  we  can  use  to  add  columns  to  the  table: 

1 Schema :: table( ' users ' , function  (Stable)  { 

Stable- > string ( 1 emai 1 ' ) ; 

3 }); 


Available  Column  Types 

Of  course,  the  schema  builder  contains  a variety  of  column  types  that  you  may  use  when  building 
your  tables: 

Command  | Description | $table->biglncrements(  ' id' );  | Incrementing  ID 

(primary  key)  using  a “UNSIGNED  BIG  INTEGER”  equivalent.  $table->biglnteger(  'votes'  ) ; | 

BIGINT  equivalent  for  the  database.  Stable-  >binary( ' data ' ) ; | BLOB  equivalent  for  the  database. 

Stable-  >boolean( ' confirmed ' ) ; | BOOLEAN  equivalent  for  the  database.  Stable-  >char(  ' name ' , 

4);  | CHAR  equivalent  with  a length.  Stable- >date(  'created_at'  );  | DATE  equivalent  for  the 
database.  $table->dateTime(  'created_at' );  | DATETIME  equivalent  for  the  database.  Stable- 
decimal  (' amount ' , 5,  2);  | DECIMAL  equivalent  with  a precision  and  scale.  Stable- >double(  'column' , 

15,  8);  | DOUBLE  equivalent  with  precision,  15  digits  in  total  and  8 after  the  decimal  point.  Stable- 
>enum( ' choices ' , ['foo',  'bar']);  | ENUM  equivalent  for  the  database.  Stable- > float  ('  amount ') ; 

| FLOAT  equivalent  for  the  database.  Stable- > increments( ' id ') ; | Incrementing  ID  (primary 
key)  using  a “UNSIGNED  INTEGER”  equivalent.  Stable- > integer(  'votes' );  | INTEGER  equiv- 
alent for  the  database.  Stable- >json(  'options' );  | JSON  equivalent  for  the  database.  Stable- 
>jsonb(  'options'  );  | JSONB  equivalent  for  the  database.  Stable- >longText(  'description'  ); 

| LONGTEXT  equivalent  for  the  database.  Stable- >mediumlnteger(  'numbers'  ) ; | MEDIUMINT 
equivalent  for  the  database.  $table->mediumText( ' description  ') ; | MEDIUMTEXT  equivalent 
for  the  database.  $table->morphs(  'taggable'  ) ; | Adds  INTEGER  taggable_id  and  STRING 
taggable_type.  Stable- >nul  lableTimestamps( ) ; | Same  as  timestamps( ),  except  allows  NULLs. 

Stable  - >rememberToken( ) ; | Addsremember_token  as  VARCHAR(lOO)  NULL.  Stable  - >smal  1 Integer ( ’ votes 1 ) ; 
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| SMALLINT  equivalent  for  the  database.  Stable- >softDeletes( ) ; | Adds  deleted_at  column  for 
soft  deletes.  Stable- >string( ' email ' ) ; | VARCHAR  equivalent  column.  $table->string(  ' name1  , 
100);  | VARCHAR  equivalent  with  a length.  Stable- >text( 'description' );  | TEXT  equiva- 
lent for  the  database.  $table->time(  'sunrise'  );  | TIME  equivalent  for  the  database.  Stable- 
>tinylnteger(  ' numbers ' ) ; | TINYINT  equivalent  for  the  database.  Stable- >timestamp(  ' added_- 
on  ' ) ; | TIMESTAMP  equivalent  for  the  database.  Stable- >timestamps( ) ; | Adds  created_at  and 
updated_at  columns.  $table->uuid(  ' id ' ) ; | UUID  equivalent  for  the  database. 

Column  Modifiers 


In  addition  to  the  column  types  listed  above,  there  are  several  other  column  “modifiers”  which  you 
may  use  while  adding  the  column.  For  example,  to  make  the  column  “nullable”,  you  may  use  the 
nullable  method: 


1 Schema :: table( ' users ' , function  (Stable)  { 
Stable- > string ( ' emai l')->nullable(); 

3 }); 


Below  is  a list  of  all  the  available  column  modifiers.  This  list  does  not  include  the  index  modifiers: 

Modifier  | Description | ->  first( ) | Place  the  column  “first”  in  the  table  (MySQL 

Only)  ->after(  'column' ) | Place  the  column  “after”  another  column  (MySQL  Only)  ->nullable( ) 

| Allow  NULL  values  to  be  inserted  into  the  column  ->default($value)  | Specify  a “default”  value 
for  the  column  ->unsigned( ) | Set  integer  columns  to  UNSIGNED 

<a  name=”changing-columns”></a>  ###  Modifying  Columns  {#migrations-modifying-columns} 

Prerequisites 

Before  modifying  a column,  be  sure  to  add  the  doctrine/dbal  dependency  to  your  composer . json 
file.  The  Doctrine  DBAL  library  is  used  to  determine  the  current  state  of  the  column  and  create  the 
SQL  queries  needed  to  make  the  specified  adjustments  to  the  column. 

Updating  Column  Attributes 

The  change  method  allows  you  to  modify  an  existing  column  to  a new  type,  or  modify  the  column’s 
attributes.  For  example,  you  may  wish  to  increase  the  size  of  a string  column.  To  see  the  change 
method  in  action,  let’s  increase  the  size  of  the  name  column  from  25  to  50: 
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1 Schema :: table( ' users ' , function  (Stable)  { 
Stable- > string ( ' name ' , 50) - > change ( ) ; 

3 }); 


We  could  also  modify  a column  to  be  nullable: 

1 Schema :: table( ' users ' , function  (Stable)  { 

Stable- > string ( 1 name ' , 50) - >nul lable( ) - > change ( ) ; 

3 }); 


Renaming  Columns 

To  rename  a column,  you  may  use  the  renameColumn  method  on  the  Schema  builder.  Before 
renaming  a column,  be  sure  to  add  the  doctrine/dbal  dependency  to  your  composer . json  file: 

1 Schema :: table( ' users ' , function  (Stable)  { 

Stable- >renameColumn( ' from  1 , ' to ' ) ; 

3 }); 


Note:  Renaming  columns  in  a table  with  a enum  column  is  not  currently  supported. 


Dropping  Columns 

To  drop  a column,  use  the  dropColumn  method  on  the  Schema  builder: 

1 Schema :: table( ' users ' , function  (Stable)  { 

Stable- >dropColumn( ' votes ' ) ; 

3 }); 


You  may  drop  multiple  columns  from  a table  by  passing  an  array  of  column  names  to  the  dropColumn 
method: 
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1 Schema :: table( ' users ' , function  (Stable)  { 

Stable- >dropColumn( [' votes ' , 'avatar' , 'location']); 

3 }); 


Note:  Before  dropping  columns  from  a SQLite  database,  you  will  need  to  add  the 
doctr ine/dbal  dependency  to  your  composer . json  fde  and  run  the  composer  update 
command  in  your  terminal  to  install  the  library. 


Note:  Dropping  or  modifying  multiple  columns  within  a single  migration  while  using  a 
SQLite  database  is  not  supported. 


Creating  Indexes 

The  schema  builder  supports  several  types  of  indexes.  First,  let’s  look  at  an  example  that  specifies 
a column’s  values  should  be  unique.  To  create  the  index,  we  can  simply  chain  the  unique  method 
onto  the  column  definition: 


1 Stable- > string ( 'email ' )->unique( ) ; 


Alternatively,  you  may  create  the  index  after  defining  the  column.  For  example: 


1 Stable- >unique( ' emai 1 ') ; 


You  may  even  pass  an  array  of  columns  to  an  index  method  to  create  a compound  index: 
1 Stable- > index( [' account_id ' , ' created_at ' ] ) ; 


Laravel  will  automatically  generate  a reasonable  index  name,  but  you  may  pass  a second  argument 
to  the  method  to  specify  the  name  yourself: 
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1 Stable- > index( ' emai 1 ' , ' my_index_name ' ) ; 


Available  Index  Types 

Command  | Description | Stable- >primary( 1 id  ' ) ; | Add  a primary  key.  $table- 

>primary(  ['  first ' , 'last']);  | Add  composite  keys.  $table->unique(  'email ' );  | Add  a unique 
index.  Stable-  >unique( ' state ' , ' my_index_name ' ) ; | Add  a custom  index  name.  Stable-  > index( ' state ' ) ; 
| Add  a basic  index. 

Dropping  Indexes 

To  drop  an  index,  you  must  specify  the  index’s  name.  By  default,  Laravel  automatically  assigns  a 
reasonable  name  to  the  indexes.  Simply  concatenate  the  table  name,  the  name  of  the  indexed  column, 
and  the  index  type.  Here  are  some  examples: 

Command  | Description | Stable- >dropPrimary(  ' users_id_primary ' );  | Drop  a 

primary  key  from  the  “users”  table.  Stable  - >dropUnique( ' users_emai  l_unique ' ) ; | Drop  a unique 
index  from  the  “users”  table.  Stable- >dropIndex(  ' geo_state_index ' ) ; | Drop  a basic  index  from 
the  “geo”  table. 

Foreign  Key  Constraints 

Laravel  also  provides  support  for  creating  foreign  key  constraints,  which  are  used  to  force  referential 
integrity  at  the  database  level.  For  example,  let’s  define  a user_id  column  on  the  posts  table  that 
references  the  id  column  on  a users  table: 


1 Schema :: table( ' posts ' , function  (Stable)  { 

Stable- > integer ( ' user_id ' ) - > unsigned ( ) ; 

3 

Stable- > foreign( ' user_id ' ) - >references( ' id ' ) - >on( ' users ' ) ; 

5 }); 


You  may  also  specify  the  desired  action  for  the  “on  delete”  and  “on  update”  properties  of  the 
constraint: 
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1 Stable- > foreign( ' user_id ' ) 

- >references( 1 id ' ) - >on( ' users ' ) 
- >onDelete( ' cascade ' ) ; 


To  drop  a foreign  key,  you  may  use  the  dropForeign  method.  Foreign  key  constraints  use  the  same 
naming  convention  as  indexes.  So,  we  will  concatenate  the  table  name  and  the  columns  in  the 
constraint  then  suffix  the  name  with  “_foreign”: 


1 Stable- >dropForeign( ' posts_user_id_foreign ' ) ; 
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Introduction 

Laravel  includes  a simple  method  of  seeding  your  database  with  test  data  using  seed  classes. 
All  seed  classes  are  stored  in  database/seeds.  Seed  classes  may  have  any  name  you  wish,  but 
probably  should  follow  some  sensible  convention,  such  as  UsersTableSeeder,  etc.  By  default,  a 
DatabaseSeeder  class  is  defined  for  you.  From  this  class,  you  may  use  the  call  method  to  run  other 
seed  classes,  allowing  you  to  control  the  seeding  order. 

Writing  Seeders 

To  generate  a seeder,  you  may  issue  the  make : seeder  Artisan  command.  All  seeders  generated  by 
the  framework  will  be  placed  in  the  database/seeds  directory: 


1 php  artisan  make: seeder  UsersTableSeeder 


A seeder  class  only  contains  one  method  by  default:  run.  This  method  is  called  when  the  db : seed 
Artisan  command  is  executed.  Within  the  run  method,  you  may  insert  data  into  your  database 
however  you  wish.  You  may  use  the  query  builder  to  manually  insert  data  or  you  may  use  Eloquent 
model  factories. 

As  an  example,  let’s  modify  the  DatabaseSeeder  class  which  is  included  with  a default  installation 
of  Laravel.  Let’s  add  a database  insert  statement  to  the  run  method: 
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1 < ?php 

2 

3 use  1 1 luminate\Database\Seeder ; 

4 use  1 1 luminate\Database\Eloquent\Model ; 

5 

6 class  DatabaseSeeder  extends  Seeder 

7 { 

8 /** 

9 * Run  the  database  seeds. 

10  * 

11  * §return  void 

12  V 

13  public  function  run() 

14  { 

15  DB :: table( 1 users ')-> insert(  [ 

16  'name'  =>  str_random(10) , 

'email'  =>  str_random(10) . '§gmail .com' , 

18  'password'  =>  bcrypt( ' secret ') , 

19  ]); 

20  } 

21  } 


Using  Model  Factories 

Of  course,  manually  specifying  the  attributes  for  each  model  seed  is  cumbersome.  Instead,  you  can 
use  model  factories  to  conveniently  generate  large  amounts  of  database  records.  First,  review  the 
model  factory  documentation  to  learn  how  to  define  your  factories.  Once  you  have  defined  your 
factories,  you  may  use  the  factory  helper  function  to  insert  records  into  your  database. 

For  example,  let’s  create  50  users  and  attach  a relationship  to  each  user: 

1 /** 

2 * Run  the  database  seeds. 

3 * 

4 * Sreturn  void 

5 V 

6 public  function  run() 

7 { 

factory(App\User  :class,  50) - >create( ) - >each( function($u)  { 

9 $u- >posts( ) - >save( factory(App\Post : : class) - >make( )) ; 

10  }); 
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11  } 


Calling  Additional  Seeders 

Within  the  DatabaseSeeder  class,  you  may  use  the  call  method  to  execute  additional  seed  classes. 
Using  the  call  method  allows  you  to  break  up  your  database  seeding  into  multiple  files  so  that  no 
single  seeder  class  becomes  overwhelmingly  large.  Simply  pass  the  name  of  the  seeder  class  you 
wish  to  run: 

1 /** 

2 * Run  the  database  seeds. 

3 * 

4 * §return  void 

5 V 

6 public  function  run() 

7 { 

8 Model  :unguard(); 

9 

10  $this->call(UsersTableSeeder : :class); 

11  $this->call(PostsTableSeeder : :class); 

12  $this->call(CominentsTableSeeder  :class); 

13 

14  Model :: reguard( ) ; 

15  } 


Running  Seeders 

Once  you  have  written  your  seeder  classes,  you  may  use  the  db : seed  Artisan  command  to  seed  your 
database.  By  default,  the  db : seed  command  runs  the  DatabaseSeeder  class,  which  may  be  used  to 
call  other  seed  classes.  However,  you  may  use  the  - -class  option  to  specify  a specific  seeder  class 
to  run  individually: 

1 php  artisan  db:seed 

2 

3 php  artisan  db:seed  - -class=UsersTableSeeder 
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You  may  also  seed  your  database  using  the  mi  grate:  re  fresh  command,  which  will  also  rollback 
and  re-run  all  of  your  migrations.  This  command  is  useful  for  completely  re-building  your  database: 

1 php  artisan  migrate : refresh  --seed 
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Introduction 

The  Eloquent  ORM  included  with  Laravel  provides  a beautiful,  simple  ActiveRecord  implementation 
for  working  with  your  database.  Each  database  table  has  a corresponding  “Model”  which  is  used  to 
interact  with  that  table.  Models  allow  you  to  query  for  data  in  your  tables,  as  well  as  insert  new 
records  into  the  table. 

Before  getting  started,  be  sure  to  configure  a database  connection  in  conf  ig/database . php.  For  more 
information  on  configuring  your  database,  check  out  the  documentation. 

Defining  Models 

To  get  started,  let’s  create  an  Eloquent  model.  Models  typically  live  in  the  app  directory,  but  you 
are  free  to  place  them  anywhere  that  can  be  auto-loaded  according  to  your  composer . json  file.  All 
Eloquent  models  extend  Illuminate\Database\Eloquent\Model  class. 

The  easiest  way  to  create  a model  instance  is  using  the  make : model  Artisan  command: 

1 php  artisan  make: model  User 


If  you  would  like  to  generate  a database  migration  when  you  generate  the  model,  you  may  use  the 
--migration  or  -m  option: 
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1 php  artisan  make: model  User  --migration 

2 

3 php  artisan  make: model  User  -m 


Eloquent  Model  Conventions 

Now,  let’s  look  at  an  example  F light  model  class,  which  we  will  use  to  retrieve  and  store  information 
from  our  flights  database  table: 

1 < ?php 

2 

3 namespace  App; 

4 

5 use  1 1 luminate\Database\Eloquent\Model ; 

6 

7 class  Flight  extends  Model 

8 { 

9 // 

10  } 


Table  Names 


Note  that  we  did  not  tell  Eloquent  which  table  to  use  for  our  FI  ight  model.  The  “snake  case”,  plural 
name  of  the  class  will  be  used  as  the  table  name  unless  another  name  is  explicitly  specified.  So, 
in  this  case,  Eloquent  will  assume  the  Flight  model  stores  records  in  the  flights  table.  You  may 
specify  a custom  table  by  defining  a table  property  on  your  model: 

1 < ?php 

2 

3 namespace  App; 

4 

5 use  1 1 luminate\Database\Eloquent\Model ; 

6 

7 class  Flight  extends  Model 

8 { 

g /** 

10  * The  table  associated  with  the  model. 
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11  * 

12  * §var  string 

13  */ 

14  protected  Stable  = ' my_f 1 ights 1 ; 

15  } 


Primary  Keys 

Eloquent  will  also  assume  that  each  table  has  a primary  key  column  named  id.  You  may  define  a 
SprimaryKey  property  to  override  this  convention. 

In  addition,  Eloquent  assumes  that  the  primary  key  is  an  incrementing  integer  value.  If  you  wish  to 
use  a non-incrementing  primary  key,  you  must  set  the  $ incrementing  property  on  your  model  to 
false. 

Timestamps 

By  default,  Eloquent  expects  created_at  and  updated_at  columns  to  exist  on  your  tables.  If  you  do 
not  wish  to  have  these  columns  automatically  managed  by  Eloquent,  set  the  $timestamps  property 
on  your  model  to  false: 


1 < ?php 

2 

3 namespace  App; 

4 

5 use  1 1 luminate\Database\Eloquent\Model ; 

6 

7 class  Flight  extends  Model 

8 { 

g /** 

10  * Indicates  if  the  model  should  be  timestamped . 

11  * 

12  * §var  bool 

13  */ 

14  public  Stimestamps  = false; 

15  } 


If  you  need  to  customize  the  format  of  your  timestamps,  set  the  $dateFormat  property  on  your 
model.  This  property  determines  how  date  attributes  are  stored  in  the  database,  as  well  as  their 
format  when  the  model  is  serialized  to  an  array  or  JSON: 
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1 < ?php 

2 

3 namespace  App; 

4 

5 use  1 1 luminate\Database\Eloquent\Model ; 

6 

7 class  Flight  extends  Model 

8 { 

g /** 

10  * The  storage  format  of  the  model 's  date  columns. 

11  * 

12  * §var  string 

13  */ 

14  protected  SdateFormat  = ' U ' ; 

15  } 


Database  Connection 

By  default,  all  Eloquent  models  will  use  the  default  database  connection  configured  for  your 
application.  If  you  would  like  to  specify  a different  connection  for  the  model,  use  the  $connection 
property: 


1 < ?php 

2 

3 namespace  App; 

4 

5 use  1 1 luminate\Database\Eloquent\Model ; 

6 

7 class  Flight  extends  Model 

8 { 

g /** 

10  * The  connection  name  for  the  model. 

11  * 

12  * §var  string 

13  */ 

14  protected  $connection  = 'connection-name'; 

15  } 
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Retrieving  Multiple  Models 

Once  you  have  created  a model  and  its  associated  database  table,  you  are  ready  to  start  retrieving 
data  from  your  database.  Think  of  each  Eloquent  model  as  a powerful  query  builder  allowing  you 
to  fluently  query  the  database  table  associated  with  the  model.  For  example: 


1 < ?php 

2 

3 namespace  App\Http\Control lers; 

4 

5 use  App\Flight; 

6 use  App\Http\Controllers\Controller; 

7 

8 class  FI ightControl ler  extends  Controller 

9 { 

10  /** 

11  * Show  a list  of  all  available  flights. 

12  * 

13  * §return  Response 

14  */ 

15  public  function  index() 

16  { 

17  $flights  = Flight: :all(); 

18 

19  return  view( 1 fl ight . index ' , [ flights'  =>  $flights]); 

20  } 

21  } 


Accessing  Column  Values 

If  you  have  an  Eloquent  model  instance,  you  may  access  the  column  values  of  the  model  by  accessing 
the  corresponding  property.  For  example,  let’s  loop  through  each  Flight  instance  returned  by  our 
query  and  echo  the  value  of  the  name  column: 

1 foreach  ($flights  as  $flight)  { 
echo  $flight->name; 

3 } 
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Adding  Additional  Constraints 

The  Eloquent  all  method  will  return  all  of  the  results  in  the  model’s  table.  Since  each  Eloquent 
model  serves  as  a query  builder,  you  may  also  add  constraints  to  queries,  and  then  use  the  get 
method  to  retrieve  the  results: 


1 Sflights  = App\Fl ight :: where( ' active ' , 1) 
- >orderBy( ' name  1 , ' desc ' ) 

- >take(10) 

->get(); 


Note:  Since  Eloquent  models  are  query  builders,  you  should  review  all  of  the  methods 
available  on  the  query  builder.  You  may  use  any  of  these  methods  in  your  Eloquent  queries. 


Collections 

For  Eloquent  methods  like  all  and  get  which  retrieve  multiple  results,  an  instance  of  Illumi- 
nate\Database\Eloquent\Col  lection  will  be  returned.  The  Collection  class  provides  a variety  of 
helpful  methods  for  working  with  your  Eloquent  results.  Of  course,  you  may  simply  loop  over  this 
collection  like  an  array: 


1 foreach  (Sflights  as  $flight)  { 
echo  $flight->name; 

3 } 


Chunking  Results 

If  you  need  to  process  thousands  of  Eloquent  records,  use  the  chunk  command.  The  chunk  method 
will  retrieve  a “chunk”  of  Eloquent  models,  feeding  them  to  a given  Closure  for  processing.  Using 
the  chunk  method  will  conserve  memory  when  working  with  large  result  sets: 
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1 FI ight : : chunk(200,  function  ($flights)  { 
foreach  ($flights  as  $flight)  { 

3 // 

4 } 

5 }); 


The  first  argument  passed  to  the  method  is  the  number  of  records  you  wish  to  receive  per  “chunk”. 
The  Closure  passed  as  the  second  argument  will  be  called  for  each  chunk  that  is  retrieved  from  the 
database. 

Retrieving  Single  Models  / Aggregates 

Of  course,  in  addition  to  retrieving  all  of  the  records  for  a given  table,  you  may  also  retrieve  single 
records  using  find  and  first.  Instead  of  returning  a collection  of  models,  these  methods  return  a 
single  model  instance: 


1 //  Retrieve  a model  by  its  primary  key... 

2 Sflight  = App\Flight : : f ind(l ) ; 

3 

4 //  Retrieve  the  first  model  matching  the  query  constraints... 

5 Sflight  = App\Flight: :where( 'active' , l)->first(); 


You  may  also  call  the  find  method  with  an  array  of  primary  keys,  which  will  return  a collection  of 
the  matching  records: 


1 Sflights  = App\Flight : : f ind( [i , 2,  3J); 


Not  Found  Exceptions 

Sometimes  you  may  wish  to  throw  an  exception  if  a model  is  not  found.  This  is  particularly  useful  in 
routes  or  controllers.  The  findOrFail  and  firstOrFail  methods  will  retrieve  the  first  result  of  the 
query.  However,  if  no  result  is  found,  a 1 1 luminate\Database\Eloquent\ModelNotFoundException 
will  be  thrown: 
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1 Smodel  = App\Flight: : findOrFail(l); 

2 

3 Smodel  = App\Flight: :where( ' legs' , 100) - > f irstOrFai 1( ) ; 


If  the  exception  is  not  caught,  a 404  HTTP  response  is  automatically  sent  back  to  the  user,  so  it  is 
not  necessary  to  write  explicit  checks  to  return  404  responses  when  using  these  methods: 


1 Route :: get( ' /api/fl ights/{ id} 1 , function  (Sid)  { 
return  App\Fl ight  : f indOrFai 1 ($id) ; 

3 }); 


Retrieving  Aggregates 

Of  course,  you  may  also  use  count,  sum,  max,  and  other  aggregate  functions  provided  by  the  query 
builder.  These  methods  return  the  appropriate  scalar  value  instead  of  a full  model  instance: 


1 Scount  = App\Flight: :where( 'active' , l)->count(); 

2 

3 $max  = App\Flight: :where( 'active' , 1 ) ->max( ' price ') ; 


Inserting  & Updating  Models 

Basic  Inserts 

To  create  a new  record  in  the  database,  simply  create  a new  model  instance,  set  attributes  on  the 
model,  then  call  the  save  method: 
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1 < ?php 

2 

3 namespace  App\Http\Control lers; 

4 

5 use  App\Flight; 

6 use  1 1 luminate\Http\Request; 

7 use  App\Http\Controllers\Controller; 

8 

9 class  FI ightControl ler  extends  Controller 

10  { 

11  /** 

12  * Create  a new  flight  instance. 

13  * 

14  * §param  Request  $request 

15  * §return  Response 

16  */ 

public  function  store(Request  $request) 

18  { 

19  //  Validate  the  request. . . 

20 

$flight  = new  Flight; 

22 

$flight->name  = $request->name; 

24 

25  $flight->save( ) ; 

26  } 

27  } 


In  this  example,  we  simply  assign  the  name  parameter  from  the  incoming  HTTP  request  to  the  name 
attribute  of  the  App\Fl  ight  model  instance.  When  we  call  the  save  method,  a record  will  be  inserted 
into  the  database.  The  created_at  and  updated_at  timestamps  will  automatically  be  set  when  the 
save  method  is  called,  so  there  is  no  need  to  set  them  manually. 

Basic  Updates 

The  save  method  may  also  be  used  to  update  models  that  already  exist  in  the  database.  To  update  a 
model,  you  should  retrieve  it,  set  any  attributes  you  wish  to  update,  and  then  call  the  save  method. 
Again,  the  updated_at  timestamp  will  automatically  be  updated,  so  there  is  no  need  to  manually 
set  its  value: 
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1 Sflight  = App\Flight : : f ind(l ) ; 

2 

3 $f light->name  = 'New  Flight  Name'; 

4 

5 $f light->save( ) ; 


Updates  can  also  be  performed  against  any  number  of  models  that  match  a given  query.  In  this 
example,  all  flights  that  are  active  and  have  a destination  of  San  Diego  will  be  marked  as  delayed: 


1 

App\Fl ight :: where( 1 active ' , 1) 

2 

- > where ( 1 destination  1 , 

' San  Diego ' ) 

3 

- >update( [' delayed ' => 

U); 

The  update  method  expects  an  array  of  column  and  value  pairs  representing  the  columns  that  should 
be  updated. 

Mass  Assignment 

You  may  also  use  the  create  method  to  save  a new  model  in  a single  line.  The  inserted  model  instance 
will  be  returned  to  you  from  the  method.  However,  before  doing  so,  you  will  need  to  specify  either  a 
fit  table  or  guarded  attribute  on  the  model,  as  all  Eloquent  models  protect  against  mass-assignment. 

A mass-assignment  vulnerability  occurs  when  a user  passes  an  unexpected  HTTP  parameter  through 
a request,  and  that  parameter  changes  a column  in  your  database  you  did  not  expect.  For  example,  a 
malicious  user  might  send  an  is_admin  parameter  through  an  HTTP  request,  which  is  then  mapped 
onto  your  model’s  create  method,  allowing  the  user  to  escalate  themselves  to  an  administrator. 

So,  to  get  started,  you  should  define  which  model  attributes  you  want  to  make  mass  assignable.  You 
may  do  this  using  the  $f  i 1 table  property  on  the  model.  For  example,  let’s  make  the  name  attribute 
of  our  Flight  model  mass  assignable: 
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1 < ?php 

2 

3 namespace  App; 

4 

5 use  1 1 luminate\Database\Eloquent\Model ; 

6 

7 class  Flight  extends  Model 

8 { 

g /** 

10  * The  attributes  that  are  mass  assignable . 

11  * 

12  * §var  array 

13  V 

14  protected  $fillable  = ['name']; 

15  } 


Once  we  have  made  the  attributes  mass  assignable,  we  can  use  the  create  method  to  insert  a new 
record  in  the  database.  The  create  method  returns  the  saved  model  instance: 


1 Sflight  = App\Flight :: create( [ ' name ' =>  'Flight  10'7); 


While  $f  i 1 table  serves  as  a “white  list”  of  attributes  that  should  be  mass  assignable,  you  may  also 
choose  to  use  $guarded.  The  $guarded  property  should  contain  an  array  of  attributes  that  you  do 
not  want  to  be  mass  assignable.  All  other  attributes  not  in  the  array  will  be  mass  assignable.  So, 
Sguarded  functions  like  a “black  list”.  Of  course,  you  should  use  either  $f  i 1 table  or  $guarded  - not 
both: 

1 < ?php 

2 

3 namespace  App; 

4 

5 use  1 1 luminate\Database\Eloquent\Model ; 

6 

7 class  Flight  extends  Model 

8 { 

g /** 

10  * The  attributes  that  aren't  mass  assignable . 

11  * 

12 


* @var  array 
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13  */ 

14  protected  Sguarded  ; ['price']; 

15  } 


In  the  example  above,  all  attributes  except  for  price  will  be  mass  assignable. 

Other  Creation  Methods 

There  are  two  other  methods  you  may  use  to  create  models  by  mass  assigning  attributes:  f i rstOr  - 
Create  and  firstOrNew.  The  f irstOrCreate  method  will  attempt  to  locate  a database  record  using 
the  given  column  / value  pairs.  If  the  model  can  not  be  found  in  the  database,  a record  will  be 
inserted  with  the  given  attributes. 

The  firstOrNew  method,  like  f irstOrCreate  will  attempt  to  locate  a record  in  the  database  matching 
the  given  attributes.  However,  if  a model  is  not  found,  a new  model  instance  will  be  returned.  Note 
that  the  model  returned  by  firstOrNew  has  not  yet  been  persisted  to  the  database.  You  will  need  to 
call  save  manually  to  persist  it: 


1 //  Retrieve  the  flight  by  the  attributes,  or  create  it  if  it  doesn't  exist... 

2 Sflight  = App\Flight : : f irstOrCreate( [' name  1 =>  'Flight  10'J); 

3 

4 //  Retrieve  the  flight  by  the  attributes,  or  instantiate  a new  instance. . . 

5 Sflight  = App\Flight : : f irstOrNew( [ ' name ' =>  'Flight  10'7); 


Deleting  Models 

To  delete  a model,  call  the  delete  method  on  a model  instance: 


1 Sflight  = App\Flight : : f ind(l ) ; 

2 

3 $f light->delete( ) ; 


Deleting  An  Existing  Model  By  Key 

In  the  example  above,  we  are  retrieving  the  model  from  the  database  before  calling  the  delete 
method.  However,  if  you  know  the  primary  key  of  the  model,  you  may  delete  the  model  without 
retrieving  it.  To  do  so,  call  the  destroy  method: 
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1 App\Flight : : destroy(l ) ; 

2 

3 App\Flight:  : destroy  ( /"l , 2,  3 ]); 

4 

5 App\Flight : : destroy(l , 2,  3); 


Deleting  Models  By  Query 

Of  course,  you  may  also  run  a delete  query  on  a set  of  models.  In  this  example,  we  will  delete  all 
flights  that  are  marked  as  inactive: 

1 $deletedRows  = App\Fl ight :: where( ' active ' , 0) - >delete( ) ; 


Soft  Deleting 


In  addition  to  actually  removing  records  from  your  database,  Eloquent  can  also  “soft  delete”  models. 
When  models  are  soft  deleted,  they  are  not  actually  removed  from  your  database.  Instead,  a 
deleted_at  attribute  is  set  on  the  model  and  inserted  into  the  database.  If  a model  has  a non- 
null deleted_at  value,  the  model  has  been  soft  deleted.  To  enable  soft  deletes  for  a model,  use  the 
1 1 luminate\Database\Eloquent\SoftDeletes  trait  on  the  model  and  add  the  deleted_at  column 
to  your  $dates  property: 


1 < ?php 

2 

3 namespace  App; 

4 

5 use  1 1 luminate\Database\Eloquent\Model ; 

6 use  1 1 luminate\Database\Eloquent\SoftDeletes; 

7 

8 class  Flight  extends  Model 

9 { 

10  use  SoftDeletes; 

11 

12  /** 

13  * The  attributes  that  should  be  mutated  to  dates. 

14  * 

15 


* §var  array 
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16  */ 

17  protected  $dates  = [ ' deleted_at ' ] ; 

18  } 


Of  course,  you  should  add  the  deleted_at  column  to  your  database  table.  The  Laravel  schema 
builder  contains  a helper  method  to  create  this  column: 

1  Schema :: table( 1 fl ights 1 , function  (Stable)  { 

Stable- >softDeletes( ) ; 

3 }); 


Now,  when  you  call  the  delete  method  on  the  model,  the  deleted_at  column  will  be  set  to  the 
current  date  and  time.  And,  when  querying  a model  that  uses  soft  deletes,  the  soft  deleted  models 
will  automatically  be  excluded  from  all  query  results. 

To  determine  if  a given  model  instance  has  been  soft  deleted,  use  the  trashed  method: 

1 if  ($f 1 ight- >trashed( ) ) { 

2 // 

3 } 


Querying  Soft  Deleted  Models 

Including  Soft  Deleted  Models 

As  noted  above,  soft  deleted  models  will  automatically  be  excluded  from  query  results.  However, 
you  may  force  soft  deleted  models  to  appear  in  a result  set  using  the  withTrashed  method  on  the 
query: 


1 $f lights  = App\Fl ight : : withTrashed( ) 

->where( 1 account_id ' , i ) 
3 ->get(); 


The  withTrashed  method  may  also  be  used  on  a relationship  query: 
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1 $f 1 ight->history( ) - >withTrashed( ) - >get( ) ; 


Retrieving  Only  Soft  Deleted  Models 

The  onlyTrashed  method  will  retrieve  only  soft  deleted  models: 

1 $f lights  = App\Fl ight : : onlyTrashed( ) 

- >where( ' airl ine_id ' , 1) 

- >get( ) ; 


Restoring  Soft  Deleted  Models 

Sometimes  you  may  wish  to  “un-delete”  a soft  deleted  model.  To  restore  a soft  deleted  model  into 
an  active  state,  use  the  restore  method  on  a model  instance: 

1 $f 1 ight- >restore( ) ; 


You  may  also  use  the  restore  method  in  a query  to  quickly  restore  multiple  models: 

1 App\Fl ight : : withTrashed( ) 

->where( ’airline_id' , 1) 

->restore( ) ; 


Like  the  withTrashed  method,  the  restore  method  may  also  be  used  on  relationships: 
1 $f 1 ight- >history( ) - >restore( ) ; 


Permanently  Deleting  Models 

Sometimes  you  may  need  to  truly  remove  a model  from  your  database.  To  permanently  remove  a 
soft  deleted  model  from  the  database,  use  the  forceDelete  method: 
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1 //  Force  deleting  a single  model  instance... 

2 $f 1 ight-> forceDelete( ) ; 

3 

4 //  Force  deleting  all  related  models... 

5 $f 1 ight->history( ) - > forceDelete( ) ; 


Query  Scopes 

Global  Scopes 

Global  scopes  allow  you  to  add  constraints  to  all  queries  for  a given  model.  Laravel’s  own  soft 
deleting  functionality  utilizes  global  scopes  to  only  pull  “non-deleted”  models  from  the  database. 
Writing  your  own  global  scopes  can  provide  a convenient,  easy  way  to  make  sure  every  query  for  a 
given  model  receives  certain  constraints. 

Writing  Global  Scopes 

Writing  a global  scope  is  simple.  Define  a class  that  implements  the  1 1 luminate\Database\Eloquent\Scope 
interface.  This  interface  requires  you  to  implement  one  method:  apply.  The  apply  method  may  add 
where  constraints  to  the  query  as  needed: 


1 < ?php 

2 

3 namespace  App\Scopes; 

4 

5 use  1 1 luminate\Database\Eloquent\Scope; 

6 use  1 1 luminate\Database\Eloquent\Model ; 

7 use  1 1 luminate\Database\Eloquent\Bui lder ; 

8 

9  class  AgeScope  implements  Scope 

10  { 

11  /** 

12  * Apply  the  scope  to  a given  Eloquent  query  builder. 

13  * 

14  * §param  \I 1 luminate\Database\Eloquent\Bui lder  $builder 

15  * §param  \Illuminate\Database\Eloquent\Model  $model 

16  * §return  void 

17  */ 

public  function  apply(Bui lder  $builder,  Model  $model) 
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19  { 

return  $bui lder- >where( 1 age ' , 200); 

21  } 

22  } 


There  is  not  a predefined  folder  for  scopes  in  a default  Laravel  application,  so  feel  free  to  make  your 
own  Scopes  folder  within  your  Laravel  application’s  app  directory. 

Applying  Global  Scopes 

To  assign  a global  scope  to  a model,  you  should  override  a given  model’s  boot  method  and  use  the 
addGlobalScope  method: 


1 < ?php 

2 

3 namespace  App; 

4 

5 use  App\Scopes\AgeScope; 

6 use  1 1 luminate\Database\Eloquent\Model ; 

7 

8 class  User  extends  Model 

9 { 

10  /** 

11  * The  "booting"  method  of  the  model. 

12  * 

13  * §return  void 

14  */ 

15  protected  static  function  boot() 

16  { 

17  parent :: boot( ) ; 

18 

static: : addGlobalScope(new  AgeScope); 

20  } 

21  } 


After  adding  the  scope,  a query  to  User : : al  1 ( ) will  produce  the  following  SQL: 


1 select  * from  'users'  where  'age'  > 200 
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Anonymous  Global  Scopes 

Eloquent  also  allows  you  to  define  global  scopes  using  Closures,  which  is  particularly  useful  for 
simple  scopes  that  do  not  warrant  a separate  class: 


1 < ?php 

2 

3 namespace  App; 

4 

5 use  1 1 luminate\Database\Eloquent\Model ; 

6 use  1 1 luminate\Database\Eloquent\Bui lder ; 

7 

8 class  User  extends  Model 

9 { 

10  /** 

11  * The  "booting"  method  of  the  model. 

12  * 

13  * @return  void 

14  */ 

15  protected  static  function  boot() 

16  { 

17  parent :: boot( ) ; 

18 

static :: addGlobalScope( 1 age ' , function(Bui lder  Sbuilder)  { 

20  $bui lder- >where( ' age ' , 200); 

21  }); 

22  } 

23  } 


The  first  argument  of  the  addGlobal  Scope ( ) serves  as  an  identifier  to  remove  the  scope: 


1 User : : withoutGlobalScope( ' age  1 ) - >get( ) ; 


Removing  Global  Scopes 

If  you  would  like  to  remove  a global  scope  for  a given  query,  you  may  use  the  withoutGl  obal  Scope 
method: 
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1 User: : withoutGlobalScope(AgeScope : :class)->get( ) ; 


If  you  would  like  to  remove  several  or  even  all  of  the  global  scopes,  you  may  use  the  withoutGlob- 
al  Scopes  method: 


1 User : : withoutGlobal Scopes ( ) ->get( ) ; 

2 

3 User : : withoutGlobal Scopes ( /"FirstScope : : class,  SecondScope : : class ] ) - >get( ) ; 


Local  Scopes 

Local  scopes  allow  you  to  define  common  sets  of  constraints  that  you  may  easily  re-use  throughout 
your  application.  For  example,  you  may  need  to  frequently  retrieve  all  users  that  are  considered 
“popular”.  To  define  a scope,  simply  prefix  an  Eloquent  model  method  with  scope. 

Scopes  should  always  return  a query  builder  instance: 


1 < ?php 

2 

3 namespace  App; 

4 

5 use  1 1 luminate\Database\Eloquent\Model ; 

6 

7 class  User  extends  Model 

8 { 

9 /** 

10  * Scope  a query  to  only  include  popular  users. 

11  * 

12  * §return  \I 1 luminate\Database\Eloquent\Bui lder 

13  */ 

14  public  function  scopePopular($query ) 

15  { 

16  return  $query- >where( 1 11 votes ' , ' 100); 

17  } 

18 

19  /** 

* Scope  a query  to  only  include  active  users. 

21  * 
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* §return  \I 1 luminate\Database\Eloquent\Bui lder 

23  */ 

24  public  function  scopeActive($query ) 

25  { 

return  $query- >where( 1 active ' , 1); 

27  } 

28  } 


Utilizing  A Query  Scope 

Once  the  scope  has  been  defined,  you  may  call  the  scope  methods  when  querying  the  model. 
However,  you  do  not  need  to  include  the  scope  prefix  when  calling  the  method.  You  can  even  chain 
calls  to  various  scopes,  for  example: 

1 $users  = App\User :: popular ()- >active( ) ->orderBy( ' created_at ') ->get( ) ; 


Dynamic  Scopes 

Sometimes  you  may  wish  to  define  a scope  that  accepts  parameters.  To  get  started,  just  add  your 
additional  parameters  to  your  scope.  Scope  parameters  should  be  defined  after  the  $query  argument: 


1 < ?php 

2 

3 namespace  App; 

4 

5 use  1 1 luminate\Database\Eloquent\Model ; 

6 

7 class  User  extends  Model 

8 { 

9 /** 

10  * Scope  a query  to  only  include  users  of  a given  type. 

11  * 

12  * §return  \I 1 luminate\Database\Eloquent\Bui lder 

13  */ 

14  public  function  scopeOfType($query , $type) 

15  { 

16 
17 


} 


return  $query- >where( 1 type ' , $type); 
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18  } 


Now,  you  may  pass  the  parameters  when  calling  the  scope: 


1 $users  = App\User :: ofType( ' admin ')- >get( ) ; 


Events 

Eloquent  models  fire  several  events,  allowing  you  to  hook  into  various  points  in  the  model’s  lifecycle 
using  the  following  methods:  creating,  created,  updating,  updated,  saving,  saved,  deleting, 
deleted,  restoring,  restored.  Events  allow  you  to  easily  execute  code  each  time  a specific  model 
class  is  saved  or  updated  in  the  database. 

Basic  Usage 

Whenever  a new  model  is  saved  for  the  first  time,  the  creating  and  created  events  will  fire.  If  a 
model  already  existed  in  the  database  and  the  save  method  is  called,  the  updating  / updated  events 
will  fire.  However,  in  both  cases,  the  saving  / saved  events  will  fire. 

For  example,  let’s  define  an  Eloquent  event  listener  in  a service  provider.  Within  our  event  listener, 
we  will  call  the  isValid  method  on  the  given  model,  and  return  false  if  the  model  is  not  valid. 
Returning  false  from  an  Eloquent  event  listener  will  cancel  the  save  / update  operation: 

1 < ?php 

2 

3 namespace  App\Providers; 

4 

5 use  App\User; 

6 use  Illuminate\Support\ServiceProvider; 

7 

8 class  AppServiceProvider  extends  ServiceProvider 

9 { 

10  /** 

11  * Bootstrap  any  application  services. 

12  * 

13 

14 

15 


* §return  void 
*/ 

public  function  boot() 
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16  { 

User :: creating( function  ($user)  { 

18  if  ( ! $user- > isVal id( ) ) { 

19  return  false; 

20  } 

21  }); 

22  } 

23 

24  /** 

25  * Register  the  service  provider. 

26  * 

27  * §return  void 

28  */ 

public  function  register() 

30  { 

31  // 

32  } 

33  } 
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Introduction 

Database  tables  are  often  related  to  one  another,  for  example,  a blog  post  may  have  many  comments, 
or  an  order  could  be  related  to  the  user  who  placed  it.  Eloquent  makes  managing  and  working  with 
these  relationships  easy,  and  supports  several  different  types  of  relationships: 

• One  To  One 

• One  To  Many 

• Many  To  Many 

• Has  Many  Through 

• Polymorphic  Relations 

• Many  To  Many  Polymorphic  Relations 

Defining  Relationships 

Eloquent  relationships  are  defined  as  functions  on  your  Eloquent  model  classes.  Since,  like  Eloquent 
models  themselves,  relationships  also  serve  as  powerful  query  builders,  defining  relationships  as 
functions  provides  powerful  method  chaining  and  querying  capabilities.  For  example: 

1 $user-> posts ( )- >where( ' active ' , l)->get(); 


But,  before  diving  too  deep  into  using  relationships,  let’s  learn  how  to  define  each  type: 
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One  To  One 

A one-to-one  relationship  is  a very  basic  relation.  For  example,  a User  model  might  be  associated 
with  one  Phone.  To  define  this  relationship,  we  place  a phone  method  on  the  User  model.  The  phone 
method  should  return  the  results  of  the  hasOne  method  on  the  base  Eloquent  model  class: 


1 < ?php 

2 

3 namespace  App; 

4 

5 use  1 1 luminate\Database\Eloquent\Model ; 

6 

7 class  User  extends  Model 

8 { 

9 /** 

10  * Get  the  phone  record  associated  with  the  user. 

11  */ 

12  public  function  phone( ) 

13  { 

14  return  $this- >hasOne( 'App\Phone' ); 

15  } 

16  } 


The  first  argument  passed  to  the  hasOne  method  is  the  name  of  the  related  model.  Once  the 
relationship  is  defined,  we  may  retrieve  the  related  record  using  Eloquent’s  dynamic  properties. 
Dynamic  properties  allow  you  to  access  relationship  functions  as  if  they  were  properties  defined  on 
the  model: 

1 $phone  = User : : find(l )->phone; 


Eloquent  assumes  the  foreign  key  of  the  relationship  based  on  the  model  name.  In  this  case,  the 
Phone  model  is  automatically  assumed  to  have  a user_id  foreign  key.  If  you  wish  to  override  this 
convention,  you  may  pass  a second  argument  to  the  hasOne  method: 


1 return  $this->hasOne( 'App\Phone' , ' foreign_key ' ) ; 


Additionally,  Eloquent  assumes  that  the  foreign  key  should  have  a value  matching  the  id  column  of 
the  parent.  In  other  words,  Eloquent  will  look  for  the  value  of  the  user’s  id  column  in  the  user_id 
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column  of  the  Phone  record.  If  you  would  like  the  relationship  to  use  a value  other  than  id,  you  may 
pass  a third  argument  to  the  hasOne  method  specifying  your  custom  key: 


1 return  $this->hasOne( 'App\Phone' , ' foreign_key ' , 1 local_key ' ) ; 


Defining  The  Inverse  Of  The  Relation 

So,  we  can  access  the  Phone  model  from  our  User.  Now,  let’s  define  a relationship  on  the  Phone 
model  that  will  let  us  access  the  User  that  owns  the  phone.  We  can  define  the  inverse  of  a hasOne 
relationship  using  the  belongsTo  method: 


1 < ?php 

2 

3 namespace  App; 

4 

5 use  1 1 luminate\Database\Eloquent\Model ; 

6 

7 class  Phone  extends  Model 

8 { 

g /** 

10  * Get  the  user  that  owns  the  phone. 

11  */ 

12  public  function  user() 

13  { 

14  return  $this->belongsTo( 'App\User 1 ); 

15  } 

16  } 


In  the  example  above,  Eloquent  will  try  to  match  the  user_id  from  the  Phone  model  to  an  id  on 
the  User  model.  Eloquent  determines  the  default  foreign  key  name  by  examining  the  name  of  the 
relationship  method  and  suffixing  the  method  name  with  _id.  However,  if  the  foreign  key  on  the 
Phone  model  is  not  user_id,  you  may  pass  a custom  key  name  as  the  second  argument  to  the 
belongsTo  method: 
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1 /** 

2 * Get  the  user  that  owns  the  phone. 

3 */ 

4 public  function  user() 

5 { 

return  $this->belongsTo( 'App\User ' , 1 2 3 4 5 6 7 8 9 10 11 foreign_key 1 ) ; 

7 } 


If  your  parent  model  does  not  use  id  as  its  primary  key,  or  you  wish  to  join  the  child  model  to  a 
different  column,  you  may  pass  a third  argument  to  the  belongsTo  method  specifying  your  parent 
table’s  custom  key: 


1 /** 

2 * Get  the  user  that  owns  the  phone. 

3 */ 

4 public  function  user() 

5 { 

return  $this->belongsTo( 'App\User ' , ' foreign_key 1 , ' other_key ' ) ; 

7 } 


One  To  Many 


A “one-to-many”  relationship  is  used  to  define  relationships  where  a single  model  owns  any  amount 
of  other  models.  For  example,  a blog  post  may  have  an  infinite  number  of  comments.  Like  all 
other  Eloquent  relationships,  one-to-many  relationships  are  defined  by  placing  a function  on  your 
Eloquent  model: 


1 < ?php 

2 

3 namespace  App; 

4 

5 use  1 1 luminate\Database\Eloquent\Model ; 

6 

7 class  Post  extends  Model 

8 { 

9 /** 

10  * Get  the  comments  for  the  blog  post. 

11  */ 
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12  public  function  commentsQ 

13  { 

14  return  $this->hasMany( 1 2 3 App\Comment ' ); 

15  } 

16  } 


Remember,  Eloquent  will  automatically  determine  the  proper  foreign  key  column  on  the  Comment 
model.  By  convention,  Eloquent  will  take  the  “snake  case”  name  of  the  owning  model  and  suffix 
it  with  _id.  So,  for  this  example,  Eloquent  will  assume  the  foreign  key  on  the  Comment  model  is 
post_id. 

Once  the  relationship  has  been  defined,  we  can  access  the  collection  of  comments  by  accessing 
the  comments  property  Remember,  since  Eloquent  provides  “dynamic  properties”,  we  can  access 
relationship  functions  as  if  they  were  defined  as  properties  on  the  model: 

1 Scomments  = App\Post : : f ind(l ) ->comments; 

2 

3 foreach  (Scomments  as  Scomment)  { 

4 // 

5 } 


Of  course,  since  all  relationships  also  serve  as  query  builders,  you  can  add  further  constraints  to 
which  comments  are  retrieved  by  calling  the  comments  method  and  continuing  to  chain  conditions 
onto  the  query: 


1 Scomments  = App\Post: : f ind(l ) ->comments( )->where( 'title' , ' foo 1 ) - > f irst( ) ; 


Like  the  hasOne  method,  you  may  also  override  the  foreign  and  local  keys  by  passing  additional 
arguments  to  the  hasMany  method: 


1 return  $this->hasMany( ' App\Comment ' , ' foreign_key ' ) ; 

2 

3 return  $this->hasMany( ' App\Comment ' , ' foreign_key ' , ' local_key ' ) ; 


Eloquent:  Relationships 


542 


Defining  The  Inverse  Of  The  Relation 

Now  that  we  can  access  all  of  a post’s  comments,  let’s  define  a relationship  to  allow  a comment  to 
access  its  parent  post.  To  define  the  inverse  of  a hasMany  relationship,  define  a relationship  function 
on  the  child  model  which  calls  the  belongsTo  method: 

1 < ?php 

2 

3 namespace  App; 

4 

5 use  1 1 luminate\Database\Eloquent\Model ; 

6 

7 class  Comment  extends  Model 

8 { 


9 

/** 

10 

* Get 

the  post  that  owns  the  comment 

11 

*/ 

12 

public 

function  post() 

13 

{ 

14 

return  $this->belongsTo( 'App\Post 

15 

} 

16  } 

Once  the  relationship  has  been  defined,  we  can  retrieve  the  Post  model  for  a Comment  by  accessing 
the  post  “dynamic  property”: 


1 Scomment  = App\Comment : : f ind(l ) ; 

2 

3 echo  $comment->post->title; 


In  the  example  above,  Eloquent  will  try  to  match  the  post_id  from  the  Comment  model  to  an  id  on 
the  Post  model.  Eloquent  determines  the  default  foreign  key  name  by  examining  the  name  of  the 
relationship  method  and  suffixing  the  method  name  with  _id.  However,  if  the  foreign  key  on  the 
Comment  model  is  not  post_id,  you  may  pass  a custom  key  name  as  the  second  argument  to  the 
belongsTo  method: 
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1 /** 

2 * Get  the  post  that  owns  the  comment. 

3 */ 

4 public  function  post() 

5 { 

return  $this->belongsTo( 'App\Post' , 1 foreign_key 1 ) ; 

7 } 


If  your  parent  model  does  not  use  id  as  its  primary  key,  or  you  wish  to  join  the  child  model  to  a 
different  column,  you  may  pass  a third  argument  to  the  belongsTo  method  specifying  your  parent 
table’s  custom  key: 

1 /** 

2 * Get  the  post  that  owns  the  comment. 

3 V 

4 public  function  post() 

5 { 

6 return  $this- >belongsTo( 'App\Post' , ' foreign_key 1 , ' other_key ' ) ; 

7 } 


Many  To  Many 

Many-to-many  relations  are  slightly  more  complicated  than  hasOne  and  hasMany  relationships.  An 
example  of  such  a relationship  is  a user  with  many  roles,  where  the  roles  are  also  shared  by  other 
users.  For  example,  many  users  may  have  the  role  of  “Admin”.  To  define  this  relationship,  three 
database  tables  are  needed:  users,  roles,  and  role_user.  The  role_user  table  is  derived  from  the 
alphabetical  order  of  the  related  model  names,  and  contains  the  user_id  and  role_id  columns. 

Many-to-many  relationships  are  defined  by  writing  a method  that  calls  the  belongsToMany  method 
on  the  base  Eloquent  class.  For  example,  let’s  define  the  roles  method  on  our  User  model: 
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1 < ?php 

2 

3 namespace  App; 

4 

5 use  1 1 luminate\Database\Eloquent\Model ; 

6 

7 class  User  extends  Model 

8 { 

g /** 

10  * The  roles  that  belong  to  the  user. 

11  */ 

12  public  function  roles() 

13  { 

14  return  $this- >belongsToMany( ' App\Role ' ) ; 

15  } 

16  } 


Once  the  relationship  is  defined,  you  may  access  the  user’s  roles  using  the  roles  dynamic  property: 

1 $user  = App\User : : f ind(l ) ; 

2 

3 foreach  ($user->roles  as  $role)  { 

4 // 

5 } 


Of  course,  like  all  other  relationship  types,  you  may  call  the  roles  method  to  continue  chaining 
query  constraints  onto  the  relationship: 


1 $roles  = App\User : : f ind(l ) ->roles( ) - >orderBy( ' name ' ) - >get( ) ; 


As  mentioned  previously,  to  determine  the  table  name  of  the  relationship’s  joining  table,  Eloquent 
will  join  the  two  related  model  names  in  alphabetical  order.  However,  you  are  free  to  override  this 
convention.  You  may  do  so  by  passing  a second  argument  to  the  belongsToMany  method: 

1 return  $this- >belongsToMany( 'App\Role' ,  *  1 user_roles 1 ) ; 
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In  addition  to  customizing  the  name  of  the  joining  table,  you  may  also  customize  the  column  names 
of  the  keys  on  the  table  by  passing  additional  arguments  to  the  belongsToMany  method.  The  third 
argument  is  the  foreign  key  name  of  the  model  on  which  you  are  defining  the  relationship,  while 
the  fourth  argument  is  the  foreign  key  name  of  the  model  that  you  are  joining  to: 

1 return  $this- >belongsToMany( ' App\Role ' , 1 user_roles 1 , 'user_id',  'role_id'); 


Defining  The  Inverse  Of  The  Relationship 

To  define  the  inverse  of  a many-to-many  relationship,  you  simply  place  another  call  to  belongsToM- 
any on  your  related  model.  To  continue  our  user  roles  example,  let’s  define  the  users  method  on  the 
Role  model: 


1 < ?php 

2 

3 namespace  App; 

4 

5 use  1 1 luminate\Database\Eloquent\Model ; 

6 

7 class  Role  extends  Model 

8 { 

g /** 

10  * The  users  that  belong  to  the  role. 

11  V 

12  public  function  users() 

13  { 

14  return  $this->belongsToMany( ’ App\User ' ) ; 

15  } 

16  } 


As  you  can  see,  the  relationship  is  defined  exactly  the  same  as  its  User  counterpart,  with  the 
exception  of  simply  referencing  the  App\User  model.  Since  we’re  reusing  the  belongsToMany 
method,  all  of  the  usual  table  and  key  customization  options  are  available  when  defining  the  inverse 
of  many-to-many  relationships. 

Retrieving  Intermediate  Table  Columns 

As  you  have  already  learned,  working  with  many-to-many  relations  requires  the  presence  of  an 
intermediate  table.  Eloquent  provides  some  very  helpful  ways  of  interacting  with  this  table.  For 
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example,  let’s  assume  our  User  object  has  many  Role  objects  that  it  is  related  to.  After  accessing 
this  relationship,  we  may  access  the  intermediate  table  using  the  pivot  attribute  on  the  models: 


1 $user  = App\User : : f ind(l ) ; 

2 

3 foreach  ($user->roles  as  $role)  { 

echo  $role->pivot->created_at; 

5 } 


Notice  that  each  Role  model  we  retrieve  is  automatically  assigned  a pivot  attribute.  This  attribute 
contains  a model  representing  the  intermediate  table,  and  may  be  used  like  any  other  Eloquent 
model. 

By  default,  only  the  model  keys  will  be  present  on  the  pivot  object.  If  your  pivot  table  contains  extra 
attributes,  you  must  specify  them  when  defining  the  relationship: 


1 return  $this->belongsToMany( 'App\Role' ) ->withPivot( 'columnl ' , 'column2'); 


If  you  want  your  pivot  table  to  have  automatically  maintained  created_at  and  updated_at 
timestamps,  use  the  withTimestamps  method  on  the  relationship  definition: 

1 return  $this- >belongsToMany( ' App\Role ' ) ->withTimestamps( ) ; 


Has  Many  Through 


The  “has-many-through”  relationship  provides  a convenient  short-cut  for  accessing  distant  relations 
via  an  intermediate  relation.  For  example,  a Country  model  might  have  many  Post  models  through 
an  intermediate  User  model.  In  this  example,  you  could  easily  gather  all  blog  posts  for  a given 
country.  Let’s  look  at  the  tables  required  to  define  this  relationship: 
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1 countries 

id  - integer 
name  - string 

4 

5 users 

id  - integer 
country_id  - integer 
name  - string 

9 

10  posts 

id  - integer 
user_id  - integer 
title  - string 


Though  posts  does  not  contain  a country_id  column,  the  hasManyThrough  relation  provides  access 
to  a country’s  posts  via  $country-  >posts.  To  perform  this  query,  Eloquent  inspects  the  country_id 
on  the  intermediate  users  table.  After  finding  the  matching  user  IDs,  they  are  used  to  query  the 
posts  table. 

Now  that  we  have  examined  the  table  structure  for  the  relationship,  let’s  define  it  on  the  Country 
model: 


1 < ?php 

2 

3 namespace  App; 

4 

5 use  1 1 luminate\Database\Eloquent\Model ; 

6 

7 class  Country  extends  Model 

8 { 

9 /** 

10  * Get  all  of  the  posts  for  the  country. 

11  */ 

12  public  function  posts() 

13  { 

14  return  $this- >hasManyThrough( 'App\Post' , 'App\User'); 

15  } 

16  } 


The  first  argument  passed  to  the  hasManyThrough  method  is  the  name  of  the  final  model  we  wish  to 
access,  while  the  second  argument  is  the  name  of  the  intermediate  model. 
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Typical  Eloquent  foreign  key  conventions  will  be  used  when  performing  the  relationship’s  queries.  If 
you  would  like  to  customize  the  keys  of  the  relationship,  you  may  pass  them  as  the  third  and  fourth 
arguments  to  the  hasManyThrough  method.  The  third  argument  is  the  name  of  the  foreign  key  on  the 
intermediate  model,  while  the  fourth  argument  is  the  name  of  the  foreign  key  on  the  final  model. 

1 class  Country  extends  Model 

2 { 

public  function  posts() 

4 { 

5 return  $this- >hasManyThrough( ' App\Post ' , 'App\User',  ’ country_id ' , 'user\ 

6 — i d ' ) ; 

7 } 

8 } 


Polymorphic  Relations 

Table  Structure 

Polymorphic  relations  allow  a model  to  belong  to  more  than  one  other  model  on  a single  association. 
For  example,  imagine  users  of  your  application  can  “like”  both  posts  and  comments.  Using 
polymorphic  relationships,  you  can  use  a single  likes  table  for  both  of  these  scenarios.  First,  let’s 
examine  the  table  structure  required  to  build  this  relationship: 


1 posts 

id  - integer 
title  - string 
body  - text 

5 

6 comments 

id  - integer 
post_id  - integer 
body  - text 

10 

11  likes 

12  id  - integer 
likeable_id  - integer 

1 ikeable_type  - string 


Two  important  columns  to  note  are  the  1 ikeable_id  and  1 ikeable_type  columns  on  the  likes  table. 
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The  1 ikeable_id  column  will  contain  the  ID  value  of  the  post  or  comment,  while  the  1 ikeable_type 
column  will  contain  the  class  name  of  the  owning  model.  The  1 ikeable_type  column  is  how  the 
ORM  determines  which  “type”  of  owning  model  to  return  when  accessing  the  likeable  relation. 

Model  Structure 

Next,  let’s  examine  the  model  definitions  needed  to  build  this  relationship: 

1 < ?php 

2 

3 namespace  App; 

4 

5 use  1 1 luminate\Database\Eloquent\Model ; 

6 

7 class  Like  extends  Model 

8 { 

9 /** 

10  * Get  all  of  the  owning  likeable  models. 

11  */ 

12  public  function  likeable() 

13  { 

14  return  $this- >morphTo( ) ; 

15  } 

16  } 

17 

18  class  Post  extends  Model 

19  { 

20  /** 

21  * Get  all  of  the  product's  likes. 

22  */ 

23  public  function  likes() 

24  { 

25  return  $this- >morphMany( ' App\Like ' , 'likeable'); 

26  } 

27  } 

28 

29  class  Comment  extends  Model 

30  { 

31  /** 

32  * Get  all  of  the  comment's  likes. 

33  */ 

34  public  function  likesQ 

35  { 

36 


return  $this- >morphMany( ' App\Like ' , 'likeable'); 
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37  } 

38  } 


Retrieving  Polymorphic  Relations 


Once  your  database  table  and  models  are  defined,  you  may  access  the  relationships  via  your  models. 
For  example,  to  access  all  of  the  likes  for  a post,  we  can  simply  use  the  likes  dynamic  property: 


1 

$post  = 

App\Post : : f ind(l ) ; 

2 

3 

foreach 

($post->likes  as  $like)  { 

4 

// 

5 

} 

You  may  also  retrieve  the  owner  of  a polymorphic  relation  from  the  polymorphic  model  by  accessing 
the  name  of  the  method  that  performs  the  call  to  morphTo.  In  our  case,  that  is  the  likeable  method 
on  the  Like  model.  So,  we  will  access  that  method  as  a dynamic  property: 


1 $like  = App\Like : : f ind(l ) ; 

2 

3 Slikeable  = $like->likeable; 


The  likeable  relation  on  the  Like  model  will  return  either  a Post  or  Comment  instance,  depending 
on  which  type  of  model  owns  the  like. 


Many  To  Many  Polymorphic  Relations 

Table  Structure 


In  addition  to  traditional  polymorphic  relations,  you  may  also  define  “many-to-many”  polymorphic 
relations.  For  example,  a blog  Post  and  Video  model  could  share  a polymorphic  relation  to  a Tag 
model.  Using  a many-to-many  polymorphic  relation  allows  you  to  have  a single  list  of  unique  tags 
that  are  shared  across  blog  posts  and  videos.  First,  let’s  examine  the  table  structure: 
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1 posts 

id  - integer 
name  - string 

4 

5 videos 

id  - integer 
name  - string 

8 

9  tags 

10  id  - integer 

name  - string 

12 

13  taggables 

tag_id  - integer 
taggable_id  - integer 
taggable_type  - string 


Model  Structure 

Next,  we’re  ready  to  define  the  relationships  on  the  model.  The  Post  and  Video  models  will  both 
have  a tags  method  that  calls  the  morphToMany  method  on  the  base  Eloquent  class: 

1 < ?php 

2 

3 namespace  App; 

4 

5 use  1 1 luminate\Database\Eloquent\Model ; 

6 

7 class  Post  extends  Model 

8 { 

g /** 

10  * Get  all  of  the  tags  for  the  post. 

11  */ 

12  public  function  tags() 

13  { 

14  return  $this- >morphToMany( ' App\Tag ' , 'taggable'); 

15  } 

16 


} 
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Defining  The  Inverse  Of  The  Relationship 

Next,  on  the  Tag  model,  you  should  define  a method  for  each  of  its  related  models.  So,  for  this 
example,  we  will  define  a posts  method  and  a videos  method: 


1 < ?php 

2 

3 namespace  App; 

4 

5 use  1 1 luminate\Database\Eloquent\Model ; 

6 

7 class  Tag  extends  Model 

8 { 

g /** 

10  * Get  all  of  the  posts  that  are  assigned  this  tag. 

11  */ 

12  public  function  posts() 

13  { 

14  return  $this- >morphedByMany( 'App\Post' , 'taggable'); 

15  } 

16 

17 

18  * Get  all  of  the  videos  that  are  assigned  this  tag. 

19  */ 

20  public  function  videos() 

21  { 

return  $this- >morphedByMany( 'App\Video' , 'taggable'); 

23  } 

24  } 


Retrieving  The  Relationship 


Once  your  database  table  and  models  are  defined,  you  may  access  the  relationships  via  your  models. 
For  example,  to  access  all  of  the  tags  for  a post,  you  can  simply  use  the  tags  dynamic  property: 


1 

$post  = 

App\Post : : f ind(l ) ; 

2 

3 

foreach 

($post->tags  as  $tag)  { 

4 

// 

5 

} 
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You  may  also  retrieve  the  owner  of  a polymorphic  relation  from  the  polymorphic  model  by  accessing 
the  name  of  the  method  that  performs  the  call  to  morphedByMany.  In  our  case,  that  is  the  posts  or 
videos  methods  on  the  Tag  model.  So,  you  will  access  those  methods  as  dynamic  properties: 


1 Stag  = App\Tag : : find(l ) ; 

2 

3 foreach  ($tag->videos  as  Svideo)  { 

4 // 

5 } 


Querying  Relations 

Since  all  types  of  Eloquent  relationships  are  defined  via  functions,  you  may  call  those  functions  to 
obtain  an  instance  of  the  relationship  without  actually  executing  the  relationship  queries.  In  addition, 
all  types  of  Eloquent  relationships  also  serve  as  query  builders,  allowing  you  to  continue  to  chain 
constraints  onto  the  relationship  query  before  finally  executing  the  SQL  against  your  database. 

For  example,  imagine  a blog  system  in  which  a User  model  has  many  associated  Post  models: 


1 < ?php 

2 

3 namespace  App; 

4 

5 use  1 1 luminate\Database\Eloquent\Model ; 

6 

7 class  User  extends  Model 

8 { 

9 /** 

10  * Get  all  of  the  posts  for  the  user. 

11  */ 

12  public  function  posts() 

13  { 

14  return  $this- >hasMany( 'App\Post' ); 

15  } 

16  } 


You  may  query  the  posts  relationship  and  add  additional  constraints  to  the  relationship  like  so: 
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1 $user  = App\User : : f ind(l ) ; 

2 

3  $user->posts( )->where( 'active' , l)->get(); 


Note  that  you  are  able  to  use  any  of  the  query  builder  methods  on  the  relationship! 

Relationship  Methods  Vs.  Dynamic  Properties 

If  you  do  not  need  to  add  additional  constraints  to  an  Eloquent  relationship  query,  you  may  simply 
access  the  relationship  as  if  it  were  a property  For  example,  continuing  to  use  our  User  and  Post 
example  models,  we  may  access  all  of  a user’s  posts  like  so: 


1 $user  = App\User : : f ind(l ) ; 

2 

3 foreach  ($user- >posts  as  $post)  { 

4 // 

5 } 


Dynamic  properties  are  “lazy  loading”,  meaning  they  will  only  load  their  relationship  data  when  you 
actually  access  them.  Because  of  this,  developers  often  use  eager  loading  to  pre-load  relationships 
they  know  will  be  accessed  after  loading  the  model.  Eager  loading  provides  a significant  reduction 
in  SQL  queries  that  must  be  executed  to  load  a model’s  relations. 

Querying  Relationship  Existence 

When  accessing  the  records  for  a model,  you  may  wish  to  limit  your  results  based  on  the  existence 
of  a relationship.  For  example,  imagine  you  want  to  retrieve  all  blog  posts  that  have  at  least  one 
comment.  To  do  so,  you  may  pass  the  name  of  the  relationship  to  the  has  method: 


1 //  Retrieve  all  posts  that  have  at  least  one  comment. . . 

2 Sposts  = App\Post :: has( ' comments ')- >get( ) ; 


You  may  also  specify  an  operator  and  count  to  further  customize  the  query: 
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1 //  Retrieve  all  posts  that  have  three  or  more  comments. . . 

2 Sposts  = Post :: has (' comments ' , 3)->get(); 


Nested  has  statements  may  also  be  constructed  using  "dot”  notation.  For  example,  you  may  retrieve 
all  posts  that  have  at  least  one  comment  and  vote: 

1 //  Retrieve  all  posts  that  have  at  least  one  comment  with  votes. . . 

2 Sposts  = Post :: has( ' comments . votes ')- >get( ) ; 


If  you  need  even  more  power,  you  may  use  the  whereHas  and  orWhereHas  methods  to  put  “where” 
conditions  on  your  has  queries.  These  methods  allow  you  to  add  customized  constraints  to  a 
relationship  constraint,  such  as  checking  the  content  of  a comment: 


1 

//  Retrieve  all  posts  with  at  least 

one  comment  containing  words  like  foo% 

2 

$posts  = Post :: whereHas( 1 2 3 4 5 6 7 8 9 comments ' , 

function  ($query)  { 

3 

$query- >where( 1 content ' , 'like' 

' f oo% ' ) ; 

4 

1 ) - >get( ) ; 

Eager  Loading 

When  accessing  Eloquent  relationships  as  properties,  the  relationship  data  is  “lazy  loaded”.  This 
means  the  relationship  data  is  not  actually  loaded  until  you  first  access  the  property.  However, 
Eloquent  can  “eager  load”  relationships  at  the  time  you  query  the  parent  model.  Eager  loading 
alleviates  the  N + 1 query  problem.  To  illustrate  the  N + 1 query  problem,  consider  a Book  model 
that  is  related  to  Author: 


1 < ?php 

2 

3 namespace  App; 

4 

5 use  1 1 luminate\Database\Eloquent\Model ; 

6 

7 class  Book  extends  Model 

8 { 

9 /** 
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10  * Get  the  author  that  wrote  the  book. 

11  */ 

12  public  function  author() 

13  { 

14  return  $this- >belongsTo( ' App\Author ' ) ; 

15  } 

16  } 


Now,  let’s  retrieve  all  books  and  their  authors: 


1 $books  = App\Book : : al 1 ( ) ; 

2 

3  foreach  ($books  as  $book)  { 

echo  $book->author->name; 

5 } 


This  loop  will  execute  1 query  to  retrieve  all  of  the  books  on  the  table,  then  another  query  for  each 
book  to  retrieve  the  author.  So,  if  we  have  25  books,  this  loop  would  run  26  queries:  1 for  the  original 
book,  and  25  additional  queries  to  retrieve  the  author  of  each  book. 

Thankfully,  we  can  use  eager  loading  to  reduce  this  operation  to  just  2 queries.  When  querying,  you 
may  specify  which  relationships  should  be  eager  loaded  using  the  with  method: 

1 $books  = App\Book :: with( ' author ')- >get( ) ; 

2 

3 foreach  ($books  as  $book)  { 

4 echo  $book->author->name; 

5 } 


For  this  operation,  only  two  queries  will  be  executed: 

1 select  * from  books 

2 

3 select  * from  authors  where  id  in  (1,  2,  3,  4,  5,  ...) 
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Eager  Loading  Multiple  Relationships 

Sometimes  you  may  need  to  eager  load  several  different  relationships  in  a single  operation.  To  do 
so,  just  pass  additional  arguments  to  the  with  method: 

1 $books  = App\Book :: with( ' author ' , ' publ isher ' ) - >get( ) ; 


Nested  Eager  Loading 


To  eager  load  nested  relationships,  you  may  use  “dot”  syntax.  For  example,  let’s  eager  load  all  of  the 
book’s  authors  and  all  of  the  author’s  personal  contacts  in  one  Eloquent  statement: 


1 $books  = App\Book :: with( ' author . contacts ')- >get( ) ; 


Constraining  Eager  Loads 

Sometimes  you  may  wish  to  eager  load  a relationship,  but  also  specify  additional  query  constraints 
for  the  eager  loading  query.  Here’s  an  example: 


1 $users  = App\User :: with( [' posts ' =>  function  ($query)  { 
$query- >where( 1 2 3 4 title ' , 'like',  '%first%'); 

3 

4 } ] ) - >get( ) ; 


In  this  example,  Eloquent  will  only  eager  load  posts  that  if  the  post’s  title  column  contains  the 
word  first.  Of  course,  you  may  call  other  query  builder  to  further  customize  the  eager  loading 
operation: 

1 $users  = App\User :: with( [' posts ' =>  function  (Iquery)  { 

2 $query- >orderBy( ' created_at ' , ' desc ' ) ; 

3 

4 } ] ) - >get( ) ; 
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Lazy  Eager  Loading 

Sometimes  you  may  need  to  eager  load  a relationship  after  the  parent  model  has  already  been 
retrieved.  For  example,  this  may  be  useful  if  you  need  to  dynamically  decide  whether  to  load  related 
models: 

1 $books  = App\Book : : al 1 ( ) ; 

2 

3 if  ($someCondition)  { 

4 $books- > load( ' author ' , 'publisher'); 

5 } 


If  you  need  to  set  additional  query  constraints  on  the  eager  loading  query,  you  may  pass  a Closure 
to  the  load  method: 


1 $books- > load( [' author ' =>  function  ($query)  { 
$query- >orderBy ( ' publ ished_date ' , ' asc ' ) ; 

3 }]); 


Inserting  Related  Models 

The  Save  Method 

Eloquent  provides  convenient  methods  for  adding  new  models  to  relationships.  For  example,  perhaps 
you  need  to  insert  a new  Comment  for  a Post  model.  Instead  of  manually  setting  the  post_id  attribute 
on  the  Comment,  you  may  insert  the  Comment  directly  from  the  relationship’s  save  method: 

1 $comment  = new  App\Comment( [ ' message ' =>  'A  new  comment. 'J); 

2 

3 $post  = App\Post : : f ind(l ) ; 

4 

5 $post- >comments( )->save($comment) ; 


Notice  that  we  did  not  access  the  comments  relationship  as  a dynamic  property.  Instead,  we  called 
the  comments  method  to  obtain  an  instance  of  the  relationship.  The  save  method  will  automatically 
add  the  appropriate  post_id  value  to  the  new  Comment  model. 
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If  you  need  to  save  multiple  related  models,  you  may  use  the  saveMany  method: 


1 $post  = App\Post : : f ind(l ) ; 

2 

3 $post- >comments( ) - >saveMany ( [ 

new  App\Comment( [' message  1 =>  'A  new  comment. ’7), 

5 new  App\Comment( [' message  1 =>  'Another  comment. '7), 

6 ]); 


Save  & Many  To  Many  Relationships 

When  working  with  a many-to-many  relationship,  the  save  method  accepts  an  array  of  additional 
intermediate  table  attributes  as  its  second  argument: 

1 App\User: : f ind(l ) ->roles( ) ->save($role,  /"'expires'  =>  SexpiresJ); 


The  Create  Method 

In  addition  to  the  save  and  saveMany  methods,  you  may  also  use  the  create  method,  which  accepts 
an  array  of  attributes,  creates  a model,  and  inserts  it  into  the  database.  Again,  the  difference  between 
save  and  create  is  that  save  accepts  a full  Eloquent  model  instance  while  create  accepts  a plain 
PHP  array: 


1 $post  = App\Post : : f ind(l ) ; 

2 

3 Scomment  = $post->comments( ) ->create( [ 

4 'message'  =>  'A  new  comment.', 

5 7); 


Before  using  the  create  method,  be  sure  to  review  the  documentation  on  attribute  mass  assignment. 

Updating  "Belongs  To"  Relationships 

When  updating  a belongsTo  relationship,  you  may  use  the  associate  method.  This  method  will  set 
the  foreign  key  on  the  child  model: 
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1 Saccount  = App\Account : : f ind(10) ; 

2 

3 $user- > account ( ) -> associate (Saccount) ; 

4 

5 $user->save( ) ; 


When  removing  a belongsTo  relationship,  you  may  use  the  dissociate  method.  This  method  will 
reset  the  foreign  key  as  well  as  the  relation  on  the  child  model: 


1 $user- > account ( ) ->dissociate( ) ; 

2 

3 $user->save( ) ; 


Many  To  Many  Relationships 

Attaching  / Detaching 

When  working  with  many-to-many  relationships,  Eloquent  provides  a few  additional  helper 
methods  to  make  working  with  related  models  more  convenient.  For  example,  let’s  imagine  a user 
can  have  many  roles  and  a role  can  have  many  users.  To  attach  a role  to  a user  by  inserting  a record 
in  the  intermediate  table  that  joins  the  models,  use  the  attach  method: 


1 $user  = App\User : : f ind(l ) ; 

2 

3 $user- >roles( )->attach($role!d); 


When  attaching  a relationship  to  a model,  you  may  also  pass  an  array  of  additional  data  to  be 
inserted  into  the  intermediate  table: 


1 $user- > roles ( )->attach($role!d,  ['expires'  =>  $expires]); 


Of  course,  sometimes  it  may  be  necessary  to  remove  a role  from  a user.  To  remove  a many-to-many 
relationship  record,  use  the  detach  method.  The  detach  method  will  remove  the  appropriate  record 
out  of  the  intermediate  table;  however,  both  models  will  remain  in  the  database: 
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1 //  Detach  a single  role  from  the  user... 

2 $user- > roles ( ) - >detach($roleId) ; 

3 

4 //  Detach  all  roles  from  the  user... 

5 $user- >roles( ) - >detach( ) ; 


For  convenience,  attach  and  detach  also  accept  arrays  of  IDs  as  input: 

1 $user  = App\User : : f ind(l ) ; 

2 

3 $user- >roles( ) - >detach(  [i. , 2,  3 ]); 

4 

5 $user- >roles( ) - >attach( [i  =>  ['expires'  =>  $expires7,  2,  3]); 


Updating  A Record  On  A Pivot  Table 

If  you  need  to  update  an  existing  row  in  your  pivot  table,  you  may  use  updateExistingPivot 
method: 


1 $user  = App\User : : f ind(l ) ; 

2 

3 $user- >roles( ) - >updateExistingPivot($role!d , $attributes) ; 


Syncing  For  Convenience 

You  may  also  use  the  sync  method  to  construct  many-to-many  associations.  The  sync  method 
accepts  an  array  of  IDs  to  place  on  the  intermediate  table.  Any  IDs  that  are  not  in  the  given  array 
will  be  removed  from  the  intermediate  table.  So,  after  this  operation  is  complete,  only  the  IDs  in  the 
array  will  exist  in  the  intermediate  table: 

1 $user->roles( )->sync( [1 , 2,  3]); 


You  may  also  pass  additional  intermediate  table  values  with  the  IDs: 
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1 $user->roles( )->sync( [1  =>  ['expires'  =>  true],  2,  3]); 


Touching  Parent  Timestamps 

When  a model  belongsTo  or  belongsToMany  another  model,  such  as  a Comment  which  belongs  to  a 
Post,  it  is  sometimes  helpful  to  update  the  parent’s  timestamp  when  the  child  model  is  updated.  For 
example,  when  a Comment  model  is  updated,  you  may  want  to  automatically  “touch”  the  updated_at 
timestamp  of  the  owning  Post.  Eloquent  makes  it  easy.  Just  add  a touches  property  containing  the 
names  of  the  relationships  to  the  child  model: 


1 < ?php 

2 

3 namespace  App; 

4 

5 use  1 1 luminate\Database\Eloquent\Model ; 

6 

7 class  Comment  extends  Model 

8 { 

9 /** 

10  * All  of  the  relationships  to  be  touched. 

11  * 

12  * §var  array 

13  */ 

14  protected  $touches  ['post']; 

15 

16  /** 

17  * Get  the  post  that  the  comment  belongs  to. 

18  */ 

19  public  function  post() 

20  { 

21  return  $this->belongsTo( 'App\Post' ); 

22  } 

23  } 


Now,  when  you  update  a Comment,  the  owning  Post  will  have  its  updated_at  column  updated  as 
well: 
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1 Scomment  = App\Comment : : f ind(l ) ; 

2 

3 Scomment -> text  = 'Edit  to  this  comment!'; 

4 

5 Scomment- >save( ) ; 


Eloquent:  Collections 

• Introduction 

• Available  Methods 

• Custom  Collections 

Introduction 

All  multi-result  sets  returned  by  Eloquent  are  an  instance  of  the  1 1 luminate\Database\Eloquent\Col  lection 
object,  including  results  retrieved  via  the  get  method  or  accessed  via  a relationship.  The  Eloquent 
collection  object  extends  the  Laravel  base  collection,  so  it  naturally  inherits  dozens  of  methods  used 
to  fluently  work  with  the  underlying  array  of  Eloquent  models. 

Of  course,  all  collections  also  serve  as  iterators,  allowing  you  to  loop  over  them  as  if  they  were 
simple  PHP  arrays: 

1 $users  = App\User :: where( ' active ' , l)->get(); 

2 

3 foreach  ($users  as  $user)  { 

4 echo  $user->name; 

5 } 


However,  collections  are  much  more  powerful  than  arrays  and  expose  a variety  of  map  / reduce 
operations  that  may  be  chained  using  an  intuitive  interface.  For  example,  let’s  remove  all  inactive 
models  and  gather  the  first  name  for  each  remaining  user: 


1 $users  = App\User :: where( ' active ' , l)->get(); 

2 

3 $names  = $users- >reject( function  ($user)  { 
return  $user- >active  ==-  false; 

5 }) 

6 - >map( function  ($user)  { 

return  $user->name; 

8 }); 
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Note:  While  most  Eloquent  collection  methods  return  a new  instance  of  an  Eloquent 
collection,  the  pluck,  keys,  zip,  collapse,  flatten  and  flip  methods  return  a base 
collection  instance. 


Available  Methods 

The  Base  Collection 

All  Eloquent  collections  extend  the  base  Laravel  collection  object;  therefore,  they  inherit  all  of  the 
powerful  methods  provided  by  the  base  collection  class: 

<style>  A>  #collection-method-list  > p { A>  column-count:  3;  -moz-column-count:  3;  -webkit- 
column-count:  3;  A>  column-gap:  2em;  -moz-column-gap:  2em;  -webkit-column-gap:  2em;  A>  } A> 
A>  #collection-method-list  a { A>  display:  block;  A>  } 

</style> 

<div  id=”collection-method-list”  markdown=”l”>  all  chunk  collapse  contains  count  diff  each  every 
filter  first  flatten  flip  forget  forPage  get  groupBy  has  implode  intersect  isEmpty  keyBy  keys  last  map 
merge  pluck  pop  prepend  pull  push  put  random  reduce  reject  reverse  search  shift  shuffle  slice  sort 
sortBy  sortByDesc  splice  sum  take  toArray  tojson  transform  unique  values  where  whereLoose  zip 
</div> 

Custom  Collections 

If  you  need  to  use  a custom  Collection  object  with  your  own  extension  methods,  you  may  override 
the  newCol  lection  method  on  your  model: 


1 < ?php 

2 

3 namespace  App; 

4 

5 use  App\CustomCol lection; 

6 use  1 1 luminate\Database\Eloquent\Model ; 

7 

8 class  User  extends  Model 

9 { 

10  /** 

11  * Create  a new  Eloquent  Collection  instance. 

12  * 

13 

14 


* §param  array  $models 

* §return  \I 1 luminate\Database\Eloquent\Col lection 
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15  */ 

16  public  function  newCol lection(array  $models  = []) 

17  { 

return  new  CustomCol lection($models) ; 

19  } 

20  } 


Once  you  have  defined  a newCol  lection  method,  you  will  receive  an  instance  of  your  custom 
collection  anytime  Eloquent  returns  a Collection  instance  of  that  model.  If  you  would  like  to  use 
a custom  collection  for  every  model  in  your  application,  you  should  override  the  newCol  lection 
method  on  a model  base  class  that  is  extended  by  all  of  your  models. 


Eloquent:  Mutators 

• Introduction 

• Accessors  & Mutators 

• Date  Mutators 

• Attribute  Casting 

Introduction 

Accessors  and  mutators  allow  you  to  format  Eloquent  attributes  when  retrieving  them  from  a model 
or  setting  their  value.  For  example,  you  may  want  to  use  the  Laravel  encrypter  to  encrypt  a value 
while  it  is  stored  in  the  database,  and  then  automatically  decrypt  the  attribute  when  you  access  it 
on  an  Eloquent  model. 

In  addition  to  custom  accessors  and  mutators,  Eloquent  can  also  automatically  cast  date  fields  to 
Carbon196  instances  or  even  cast  text  fields  to  JSON. 

Accessors  & Mutators 

Defining  An  Accessor 

To  define  an  accessor,  create  a getFooAttribute  method  on  your  model  where  Foo  is  the  “camel” 
cased  name  of  the  column  you  wish  to  access.  In  this  example,  we’ll  define  an  accessor  for  the 
first_name  attribute.  The  accessor  will  automatically  be  called  by  Eloquent  when  attempting  to 
retrieve  the  value  of  f irst_name: 

1 < ?php 

2 

3 namespace  App; 

4 

5 use  1 1 luminate\Database\Eloquent\Model ; 

6 

7 class  User  extends  Model 

8 { 

9 /** 

10  * Get  the  user's  first  name. 

11  * 


196https://github.com/briaimesbitt/Caxbon 
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12  * §param  string  $value 

13  * @return  string 

14  */ 

15  public  function  getFirstNameAttribute($value) 

16  { 

17  return  ucf irst($value) ; 

18  } 

19  } 


As  you  can  see,  the  original  value  of  the  column  is  passed  to  the  accessor,  allowing  you  to  manipulate 
and  return  the  value.  To  access  the  value  of  the  mutator,  you  may  simply  access  the  first_name 
attribute: 


1 $user  = App\User : : f ind(l ) ; 

2 

3 SfirstName  = $user- > f irst_name; 


Defining  A Mutator 

To  define  a mutator,  define  a setFooAttribute  method  on  your  model  where  Foo  is  the  “camel” 
cased  name  of  the  column  you  wish  to  access.  So,  again,  let’s  define  a mutator  for  the  first_- 
name  attribute.  This  mutator  will  be  automatically  called  when  we  attempt  to  set  the  value  of  the 
f irst_name  attribute  on  the  model: 

1 < ?php 

2 

3 namespace  App; 

4 

5 use  1 1 luminate\Database\Eloquent\Model ; 

6 

7 class  User  extends  Model 

8 { 

g /** 

10  * Set  the  user's  first  name. 

11  * 

12  * §param  string  $value 

13  * §return  string 

14  */ 

15  public  function  setFirstNameAttribute($value) 
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16  { 

17  $this- attributes [ ' f irst_name ' ] = strtolower($value) ; 

18  } 

19  } 


The  mutator  will  receive  the  value  that  is  being  set  on  the  attribute,  allowing  you  to  manipulate  the 
value  and  set  the  manipulated  value  on  the  Eloquent  model’s  internal  $attributes  property.  So,  for 
example,  if  we  attempt  to  set  the  first_name  attribute  to  Sally: 


1 $user  = App\User : : f ind(l ) ; 

2 

3 $user->first_name  = 'Sally'; 


In  this  example,  the  setFirstNameAttribute  function  will  be  called  with  the  value  Sally.  The 
mutator  will  then  apply  the  strto lower  function  to  the  name  and  set  its  value  in  the  internal 
$attributes  array. 


Date  Mutators 

By  default,  Eloquent  will  convert  the  created_at  and  updated_at  columns  to  instances  of  Carbon197, 
which  provides  an  assortment  of  helpful  methods,  and  extends  the  native  PHP  DateTime  class. 

You  may  customize  which  fields  are  automatically  mutated,  and  even  completely  disable  this 
mutation,  by  overriding  the  $dates  property  of  your  model: 

1 < ?php 

2 

3 namespace  App; 

4 

5 use  1 1 luminate\Database\Eloquent\Model ; 

6 

7 class  User  extends  Model 

8 { 

g /** 

10  * The  attributes  that  should  be  mutated  to  dates. 

11  * 

12  * §var  array 


197https://github.com/briaimesbitt/Carbon 
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13 

14 


*/ 

protected  Sdates  [ ' created_at ' , ' updated_at ' , 1 deleted_at ' ] ; 


15  } 


When  a column  is  considered  a date,  you  may  set  its  value  to  a UNIX  timestamp,  date  string  (Y-m-d), 
date-time  string,  and  of  course  a DateTime  / Carbon  instance,  and  the  date’s  value  will  automatically 
be  correctly  stored  in  your  database: 


1 $user  = App\User : : f ind(l ) ; 

2 

3 $user- >deleted_at  = Carbon :: now( ) ; 

4 

5 $user- >save( ) ; 


As  noted  above,  when  retrieving  attributes  that  are  listed  in  your  $dates  property,  they  will 
automatically  be  cast  to  Carbon198  instances,  allowing  you  to  use  any  of  Carbon’s  methods  on  your 
attributes: 


1 $user  = App\User : : f ind(l ) ; 

2 

3 return  $user- >deleted_at- >getTimestamp( ) ; 


By  default,  timestamps  are  formatted  as  'Y-m-d  H : i : s ' . If  you  need  to  customize  the  timestamp 
format,  set  the  SdateFormat  property  on  your  model.  This  property  determines  how  date  attributes 
are  stored  in  the  database,  as  well  as  their  format  when  the  model  is  serialized  to  an  array  or  JSON: 


1 < ?php 

2 

3 namespace  App; 

4 

5 use  1 1 luminate\Database\Eloquent\Model ; 

6 

7 class  Flight  extends  Model 

8 { 


9 


/** 


198i 


https://github.com/briannesbitt/Carbon 
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10  * The  storage  format  of  the  model  's  date  columns. 

11  * 

12  * §var  string 

13  */ 

14  protected  IdateFormat  = ' U ' ; 

15  } 


Attribute  Casting 

The  $casts  property  on  your  model  provides  a convenient  method  of  converting  attributes  to 
common  data  types.  The  $casts  property  should  be  an  array  where  the  key  is  the  name  of  the 
attribute  being  cast,  while  the  value  is  the  type  you  wish  to  cast  to  the  column  to.  The  supported 
cast  types  are:  integer,  real,  float,  double,  string,  boolean,  object,  array, collection, date  and 
datetime. 

For  example,  let’s  cast  the  is_admin  attribute,  which  is  stored  in  our  database  as  an  integer  (0  or  l) 
to  a boolean  value: 


1 < ?php 

2 

3 namespace  App; 

4 

5 use  1 1 luminate\Database\Eloquent\Model ; 

6 

7 class  User  extends  Model 

8 { 

9 /** 

10  * The  attributes  that  should  be  casted  to  native  types. 

11  * 

12  * §var  array 

13  */ 

14  protected  leasts  = [ 

15  'is_admin'  =>  'boolean' , 

16  ]; 

17  } 


Now  the  is_admin  attribute  will  always  be  cast  to  a boolean  when  you  access  it,  even  if  the 
underlying  value  is  stored  in  the  database  as  an  integer: 
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1 $user  = App\User : : f ind(l ) ; 

2 

3 if  ($user->is_admin)  { 

4 // 

5 } 


Array  Casting 

The  array  cast  type  is  particularly  useful  when  working  with  columns  that  are  stored  as  serialized 
JSON.  For  example,  if  your  database  has  a TEXT  field  type  that  contains  serialized  JSON,  adding  the 
array  cast  to  that  attribute  will  automatically  deserialize  the  attribute  to  a PHP  array  when  you 
access  it  on  your  Eloquent  model: 


1 < ?php 

2 

3 namespace  App; 

4 

5 use  1 1 luminate\Database\Eloquent\Model ; 

6 

7 class  User  extends  Model 

8 { 

9 /** 

10  * The  attributes  that  should  be  casted  to  native  types. 

11  * 

12  * @var  array 

13  */ 

14  protected  leasts  = [ 

15  'options'  =>  'array', 

16  ]; 

17  } 


Once  the  cast  is  defined,  you  may  access  the  options  attribute  and  it  will  automatically  be 
deserialized  from  JSON  into  a PHP  array.  When  you  set  the  value  of  the  options  attribute,  the 
given  array  will  automatically  be  serialized  back  into  JSON  for  storage: 
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1 $user  = App\User : : f ind(l ) ; 

2 

3 Soptions  = $user->options; 

4 

5 Soptions/"  'key ']  = 'value'; 

6 

7 $user->options  = Soptions; 

8 

9 $user->save( ) ; 


Eloquent:  Serialization 

• Introduction 

• Basic  Usage 

• Hiding  Attributes  From  JSON 

• Appending  Values  To  JSON 


Introduction 

When  building  JSON  APIs,  you  will  often  need  to  convert  your  models  and  relationships  to  arrays 
or  JSON.  Eloquent  includes  convenient  methods  for  making  these  conversions,  as  well  as  controlling 
which  attributes  are  included  in  your  serializations. 

Basic  Usage 

Converting  A Model  To  An  Array 

To  convert  a model  and  its  loaded  relationships  to  an  array,  you  may  use  the  toArray  method.  This 
method  is  recursive,  so  all  attributes  and  all  relations  (including  the  relations  of  relations)  will  be 
converted  to  arrays: 


1 $user  = App\User :: with( ' roles  1 )- > first( ) ; 

2 

3 return  $user- >toArray( ) ; 


You  may  also  convert  collections  to  arrays: 

1 $users  = App\User : : al 1 ( ) ; 

2 

3 return  Susers- >toArray( ) ; 
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Converting  A Model  To  JSON 

To  convert  a model  to  JSON,  you  may  use  the  toJson  method.  Like  toArray,  the  toJson  method  is 
recursive,  so  all  attributes  and  relations  will  be  converted  to  JSON: 


1 $user  = App\User : : f ind(l ) ; 

2 

3 return  $user- >toJson( ) ; 


Alternatively,  you  may  cast  a model  or  collection  to  a string,  which  will  automatically  call  the  toJson 
method: 

1 $user  = App\User : : f ind(l ) ; 

2 

3 return  (string)  $user; 


Since  models  and  collections  are  converted  to  JSON  when  cast  to  a string,  you  can  return  Eloquent 
objects  directly  from  your  application’s  routes  or  controllers: 

1 Route :: get( ' users ' , function  ()  { 
return  App\User : : al 1 ( ) ; 

3 }); 


Hiding  Attributes  From  JSON 

Sometimes  you  may  wish  to  limit  the  attributes,  such  as  passwords,  that  are  included  in  your  model’s 
array  or  JSON  representation.  To  do  so,  add  a $hidden  property  definition  to  your  model: 
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1 < ?php 

2 

3 namespace  App; 

4 

5 use  1 1 luminate\Database\Eloquent\Model ; 

6 

7 class  User  extends  Model 

8 { 

g /** 

10  * The  attributes  that  should  be  hidden  for  arrays. 

11  * 

12  * §var  array 

13  V 

14  protected  Shidden  [ password']; 

15  } 


Note:  When  hiding  relationships,  use  the  relationship’s  method  name,  not  its  dynamic 
property  name. 


Alternatively,  you  may  use  the  visible  property  to  define  a white-list  of  attributes  that  should  be 
included  in  your  model’s  array  and  JSON  representation: 


1 < ?php 

2 

3 namespace  App; 

4 

5 use  1 1 luminate\Database\Eloquent\Model ; 

6 

7 class  User  extends  Model 

8 { 

g /** 

10  * The  attributes  that  should  be  visible  in  arrays. 

11  * 

12  * @var  array 

13  */ 

14  protected  Svisible  [ ' f irst_name ' , 'last_name  ]; 

15  } 
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Temporarily  Exposing  Hidden  Properties 

If  you  would  like  to  make  some  typically  hidden  attributes  visible  on  a given  model  instance, 
you  may  use  the  makeVisible  method.  The  makeVisible  method  returns  the  model  instance  for 
convenient  method  chaining: 


1 return  $user- >makeVisible( ' attribute ')- >toArray( ) ; 


Appending  Values  To  JSON 

Occasionally,  you  may  need  to  add  array  attributes  that  do  not  have  a corresponding  column  in  your 
database.  To  do  so,  first  define  an  accessor  for  the  value: 


1 < ?php 

2 

3 namespace  App; 

4 

5 use  1 1 luminate\Database\Eloquent\Model ; 

6 

7 class  User  extends  Model 

8 { 

g /** 

10  * Get  the  administrator  flag  for  the  user. 

11  * 

12  * § return  bool 

13  */ 

14  public  function  getIsAdminAttribute( ) 

15  { 

16  return  $this- attributes [' admin  ] 'yes'; 

17  } 

18  } 


Once  you  have  created  the  accessor,  add  the  attribute  name  to  the  appends  property  on  the  model: 
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1 < ?php 

2 

3 namespace  App; 

4 

5 use  1 1 luminate\Database\Eloquent\Model ; 

6 

7 class  User  extends  Model 

8 { 

g /** 

10  * The  accessors  to  append  to  the  model 's  array  form. 

11  * 

12  * §var  array 

13  V 

14  protected  Sappends  [ ' is_admin ' ] ; 

15  } 


Once  the  attribute  has  been  added  to  the  appends  list,  it  will  be  included  in  both  the  model’s  array 
and  JSON  forms.  Attributes  in  the  appends  array  will  also  respect  the  visible  and  hidden  settings 
configured  on  the  model. 


